Memory

​

Overview

Zeus’s memory system provides the Agent with cross-session user awareness capabilities. By extracting, storing, and retrieving key information from conversations, the Agent continuously accumulates understanding of users and projects, delivering personalized, contextually coherent interactions. The memory system addresses three core problems:

• Personalization: Remember user preferences (coding style, language, toolchain) without requiring repeated explanation
• Context Continuity: Maintain awareness of project background and technical decisions across sessions
• Intelligent Reasoning: Make more accurate judgments and suggestions based on historical memory

---

​

Architecture

​

Four-Layer Memory Model

Zeus’s memory system consists of four layers with different lifecycles, forming a complete cognitive hierarchy from ephemeral runtime state to permanent user profiles.

​

Three-Layer Data Architecture (memU)

Long-term Memory adopts a memU-inspired three-layer structure, progressively abstracting raw resources into structured profiles: Data flows upward: Layer 1 raw resources are extracted into Layer 2 memory items, which are then aggregated into Layer 3 profiles.

---

​

Data Model

​

Memory Item

Memory items are the core data unit of the system. Each memory entry contains content, classification, scope, and metadata. Key fields include:

• content: Memory content text
• memory_type: Memory type classification
• scope / scope_id: Scope (user / project / session) and corresponding ID
• source / source_id: Source (user / ai / knowledge_base / project_resource) and associated ID
• confidence: Confidence score (0.0 ~ 1.0)
• visibility: Visibility range (public / members / owner_only), only effective for project scope
• status: Status (active / archived / superseded)
• last_used_at: Last retrieval timestamp

​

Memory Type

Each type corresponds to different kinds of information. The Agent must select the correct type when extracting memories:

​

Memory Scope

Scope determines the visibility and lifecycle of memories:

​

User Profile

The user profile aggregates global user characteristics and is injected into the System Prompt for every conversation. Key fields include:

• username: Username
• background: User background description
• profession: Profession
• communication_style: Communication style (concise / detailed / technical)
• response_format: Response format preference (markdown / plain / code)
• language_preference: Language preference (zh-CN / en / ja, etc.)
• characteristics: Personality traits
• content: Custom Instructions
• expertise_areas: Areas of expertise
• programming_languages: Programming languages
• frequently_used_tools: Frequently used tools

​

Project Profile

The project profile records team-shared project context. Key fields include:

• project_goal: Project goal
• tech_stack: Technology stack
• constraints: Constraints
• key_decisions: Key decisions (including decision content, rationale, and timestamp)
• team_conventions: Team conventions
• current_phase: Current phase

---

​

Core Components

​

MemoryService

MemoryService is the core service of the memory system, managing memory read/write and retrieval. It interacts with both PostgreSQL (metadata) and pgvector (vector index).

​

Key Methods

​

Memory Gate

The gate layer performs multi-dimensional validation before memory writes, preventing low-quality, sensitive, or duplicate information from entering the memory store: Gate configuration supports environment variable overrides:

​

Memory Tools

The Agent autonomously manages memories through four built-in tools: Tools receive user_id, project_id, session_id via RunnableConfig, enabled by default in Agent mode (enable_memory=True).

---

​

Agent Integration

​

Complete Data Flow

The following diagram shows how the memory system participates in a complete Agent invocation:

​

System Prompt Injection

During the System Prompt assembly (steps 12–13 of the 15-step pipeline), the system fetches profile and memory data and appends them as structured text at the end of the prompt. Specifically:

• User Profile — background, communication style, expertise areas, programming languages, and frequently used tools
• Project Profile — project goals, tech stack, constraints, key decisions, and current phase
• Related Memories — memory entries semantically related to the current conversation, each annotated with its scope identifier and type

This injection is handled by _fetch_profile() and _fetch_relevant_memories() within _init_context(). For the full System Prompt assembly pipeline, see System Prompt. For how this fits into the broader Context, see Context.

​

Retrieval Ranking Algorithm

After multi-scope memory retrieval, results are merged and sorted by weighted scoring: final_score = similarity × 0.5 + confidence × 0.3 + scope_priority × 0.2 Where scope priority: After deduplication within the same type, the highest-scoring entries are retained, and the final Top K results are returned.

---

​

Permission Model

Project-level memories have fine-grained permission control: The visibility field further controls the visible range:

• public: Visible to all project members
• members: Visible to project members (default)
• owner_only: Visible to the creator only

---

​

Vector Storage

Memory vector storage uses the PostgreSQL pgvector extension, sharing underlying infrastructure with the RAG knowledge base: Each user can configure their own Embedding API (model, Base URL, API Key). The system automatically loads the corresponding configuration via create_embeddings(user_id).

---

​

Episodic Memory & Checkpoint

Episodic Memory is implemented through LangGraph’s PostgresSaver, responsible for session state persistence and recovery: Checkpoint stored content: Additionally, the session_state_snapshot table and checkpoint_archive table are used for session state snapshots and expired checkpoint archival, respectively.