Memory System

The Memory System gives AI a “memory.” It not only tracks key decisions and progress throughout a single conversation, but also remembers your preferences, project context, and working habits across sessions — the more you use it, the better it understands you.

Dual-Layer Architecture

The memory system is divided into two layers, each with its own role:

	Session Memory	User Memory
Scope	Single session	Across all sessions
Lifecycle	During session	Long-term retention
Core Purpose	Compression summaries, cross-turn context	Personalization, knowledge inheritance
Extraction Method	Automatic extraction + Agent-initiated saves	Agent-initiated saves
Capacity Limit	20 entries, ~12K tokens	1,000 entries

Session Memory

Five Categories

Session Memory distills key information from ongoing conversations into 5 categories:

Category	Description	Example
🎯 decision	Technical decisions and design choices	“Choose PostgreSQL as the database”
📍 context	Current task context	“Implementing user login functionality”
📊 progress	Task progress and completion status	“Database schema design completed”
🚧 issue	Encountered issues and solutions	“CORS error, resolved by configuring middleware”
💡 learnings	Lessons learned and takeaways	“Connection pooling can significantly improve performance”

Dual-Track Extraction

Session Memory accumulates through automatic extraction and agent-initiated saves via two parallel paths:

Automatic extraction is performed by a background agent, triggered by the following conditions:

Condition	Description
Initial threshold	Context tokens >= 10,000
Growth threshold	Token growth >= 5,000
Tool calls	Number of tool calls >= 3
Conversation breakpoint	Token threshold met + no tool calls in the last turn

💡 The background agent shares the prompt cache with the main conversation, is hard-limited to at most 5 turns, and has virtually no impact on main conversation performance.

Capacity Limits

Limit	Value	Description
Maximum entries	20	Storage limit, per single session
Total token limit	~12,000	Storage limit, approximately 9 pages of documentation
Injection count	5 entries per turn, up to 5,000 tokens	Injected into context each turn
Overflow strategy	Delete oldest	Retain the most recent information

User Memory

Four Categories

User Memory records long-term knowledge across sessions, organized into 4 categories:

Category	Description	Example
👤 user	User role, goals, preferences	“10 years of Go experience, new to React”
💬 feedback	User guidance on working methods	“Don’t mock the database in tests”
📁 project	Project progress, goals, decision context	“Merge freeze since 2026-03-05”
🔗 reference	Pointers to external systems	“Pipeline bug in Linear INGEST project”

Importance Levels

Each User Memory entry has an importance rating that affects retrieval priority:

feedback and project type memories also contain a special structure:

Rule/Fact
Why: The reason provided by the user
How to apply: When/where this guidance applies

📌 This Why + How to apply structure helps AI understand the context and apply the right rules in the right scenarios.

Capacity Limits

Limit	Value	Description
Maximum entries	1,000	Per single user
Per-entry token limit	~1,000	-
Overflow strategy	No automatic eviction	Only manual deletion supported (delete_user_memory tool)

Embedding Retrieval

User Memory uses a hybrid retrieval strategy that balances semantic understanding with exact matching:

Stage	Strategy	Description
Vector search	Cosine similarity	Semantic-level matching, Top 10
Keyword search	Full-text search + tag matching	Exact keyword matching, Top 10
Fusion ranking	RRF algorithm	score = Σ 1/(60 + rank), merges both result sets
Weighted filtering	Importance + access frequency + recency	Important and frequently used memories are prioritized
Final output	Top 5	The 5 most relevant memories

Injection Strategy

Memories enter the AI’s context through a carefully designed injection strategy:

Memory Type	Injection Timing	Injection Count	Trigger
Session Memory	Before each turn	5 entries, up to 5,000 tokens	Automatic
User Memory	Every turn	Dynamic importance filtering	Based on embedding retrieval
Session Memory (during compression)	Auto Compact triggered	All entries	Used as compression summary

💡 User Memory is dynamically filtered by importance: critical / high are all injected, medium injects up to 10 entries per category, low is not injected.

Session Memory Compact

When the context needs to be compressed, Session Memory can serve as a summary at zero cost:

Approach	Cost	Summary Quality	Speed
Session Memory Compact	Zero API cost	Higher (continuously updated)	Faster
Standard Auto Compact	One LLM call	Average (generated in one shot)	Slower

📌 Session Memory is continuously accumulated throughout the conversation, producing a more complete and accurate summary than one generated in a single pass during compression.

Future Roadmap

Feature	Description
🌙 Memory Consolidation (Dream Task)	Periodically merge duplicate memories, delete outdated ones, and extract shared knowledge
👥 Team Memory	Support team-shared preferences, standards, and best practices
📊 Memory Visualization	View, edit, search memories in the UI, and view usage statistics

Next Steps

• Context Management — Learn how the memory system works with the compression system
• Remote Tool Calling — Learn how AI executes tools on the frontend
• Session Management — Understand memory in the context of sessions