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.

Layer	Lifecycle	Storage	Responsibility
Working Memory	Single Agent invocation	In-memory	Temporary context for task execution: todo_list, tool_calls, reasoning state
Short-term Memory	Single session	PostgreSQL (message table)	Current session conversation history, automatically compressed via SummarizationMiddleware
Long-term Memory	Permanent (user-managed)	PostgreSQL + pgvector	Cross-session user/project information, supports semantic retrieval
Episodic Memory	Recoverable	PostgreSQL (checkpoint table)	Session state snapshots, supports page refresh, interrupt recovery, error retry

Three-Layer Data Architecture (memU)

Long-term Memory adopts a memU-inspired three-layer structure, progressively abstracting raw resources into structured profiles:

Layer	Name	Content	Description
Layer 1	Resource Layer	Chat conversations, Knowledge Base documents, Project Resources	Raw data sources — the original material from which memories are extracted
Layer 2	Memory Item Layer	preference, fact, skill, habit, event, context, constraint, decision	Structured memory entries extracted from raw data, categorized by type
Layer 3	Profile Layer	User Profile (global preferences, professional background), Project Profile (tech stack, constraints, decisions)	Aggregated profiles injected directly into the System Prompt

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:

Type	Semantics	Example
`preference`	User preferences	Likes concise code, prefers dark theme
`fact`	Factual information	User is a frontend engineer, named John
`skill`	Skill level	Proficient in React, expert in TypeScript
`habit`	Usage habits	Frequently uses VS Code, prefers Git Flow
`event`	Important events	Completed Project A launch
`context`	Project context	Currently developing the payment module
`constraint`	Constraints	Project must support PostgreSQL 16
`decision`	Decision records	Chose Next.js over Remix

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

Method	Responsibility
`add_explicit_memory()`	Save memory — gate validation → pgvector write → PostgreSQL write
`search_memories()`	Semantic retrieval — multi-scope search → merge and sort → return Top K
`validate_memory()`	Content validation — confidence, sensitive information, content length
`check_duplicate()`	Deduplication — pgvector similarity ≥ 0.85 is considered duplicate
`check_rate_limit()`	Rate limiting — max 3 extractions per session per 24h
`get_profile_for_agent()`	Get user/project profile for System Prompt injection
`format_memories_for_prompt()`	Format memories into prompt-readable text

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:

Parameter	Default	Environment Variable
Minimum confidence	0.7	`MEMORY_MIN_CONFIDENCE`
Deduplication threshold	0.85	`MEMORY_DUPLICATE_THRESHOLD`
Rate limit	3 times/session/24h	`MEMORY_MAX_EXTRACTIONS`
Minimum content length	5 characters	`MEMORY_MIN_LENGTH`
Maximum content length	2000 characters	`MEMORY_MAX_LENGTH`

Memory Tools

The Agent autonomously manages memories through two built-in tools:

Tool	Trigger Scenario	Parameters
`memory_add`	User says “remember”, “remember this”, “I am…”	`content`, `memory_type`, `scope`
`memory_search`	Agent needs to recall user information	`query`, `k`, `memory_type`, `scope`

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:

Scope	Priority Weight	Description
session	1.0	Most relevant to current session
project	0.8	Project context is secondary
user	0.6	Global information as baseline

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:

Role	Read	Create	Edit	Delete
Owner	All	All	All	All
Admin	All	All	All	All
Editor	All	All	Own creations only	Own creations only
Viewer	All	No	No	No

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:

Configuration	Default	Description
Embedding Model	`text-embedding-3-small`	Supports user-customized models
Vector Dimensions	1536	Matches the model
Similarity Metric	Cosine	Cosine similarity
Collection Name	`memory`	Dedicated memory collection

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:

Data	Description
messages	Complete message history
agent_state	Agent internal state (todo_list, reasoning context)
tool_states	Tool execution states
pending_tool_calls	Operations pending user approval (HITL)

Additionally, the session_state_snapshot table and checkpoint_archive table are used for session state snapshots and expired checkpoint archival, respectively.

Get Started

Fundamentals

Core Capabilities

Infra

Channels

Overview

Architecture

Four-Layer Memory Model

Three-Layer Data Architecture (memU)

Data Model

Memory Item

Memory Type

Memory Scope

User Profile

Project Profile

Core Components

MemoryService

Key Methods

Memory Gate

Memory Tools

Agent Integration

Complete Data Flow

System Prompt Injection

Retrieval Ranking Algorithm

Permission Model

Vector Storage

Episodic Memory & Checkpoint

​Overview

​Architecture

​Four-Layer Memory Model

​Three-Layer Data Architecture (memU)

​Data Model

​Memory Item

​Memory Type

​Memory Scope

​User Profile

​Project Profile

​Core Components

​MemoryService

​Key Methods

​Memory Gate

​Memory Tools

​Agent Integration

​Complete Data Flow

​System Prompt Injection

​Retrieval Ranking Algorithm

​Permission Model

​Vector Storage

​Episodic Memory & Checkpoint

Overview

Architecture

Four-Layer Memory Model

Three-Layer Data Architecture (memU)

Data Model

Memory Item

Memory Type

Memory Scope

User Profile

Project Profile

Core Components

MemoryService

Key Methods

Memory Gate

Memory Tools

Agent Integration

Complete Data Flow

System Prompt Injection

Retrieval Ranking Algorithm

Permission Model

Vector Storage

Episodic Memory & Checkpoint