Memory
Durable, persistent intelligence that survives across sessions. The more you use it, the better agents perform.
How Memory Works
Memory operates on a three-pipeline model that runs automatically during the execution lifecycle. Each pipeline handles a distinct phase of knowledge management.
Recall
Before executionQueries memory for relevant prior context and injects it into the agent's prompt. The agent starts every session aware of past decisions, known procedures, and learned principles.
Index
After executionIndexes completed session transcripts and tickets into a full-text search database, making them available for future recall queries.
Extract
After executionAnalyzes indexed sessions to extract high-value, durable learnings as structured records. Only concrete facts are persisted — never chain-of-thought, raw transcripts, or debug artifacts.
Memory Scopes
Memory is organized into two scopes that work together during recall. Both scopes are queried simultaneously so agents receive both project-specific knowledge and your personal preferences in every session.
| Project Scope | Assistant Scope | |
|---|---|---|
| Stores | Decisions, procedures, incidents, principles, preferences tied to this codebase | Your personal preferences, communication rules, and interaction patterns across all projects |
| Indexed | Session transcripts, tickets, and records | Records only (no session transcripts) |
| Shared | Across all agents working on the same project | Across all projects for the same user |
| Example | "Use pnpm, not npm" for this repo | "Prefer concise responses" everywhere |
Assistant scope follows you across projects. When an agent learns that you prefer snake_case naming or short commit messages, that preference applies to every project you work on.
Record Categories
Every memory record belongs to one of five categories. The extraction pipeline classifies records automatically, and you can reclassify them manually if needed.
| Category | What it captures | Temporal |
|---|---|---|
decisions | Implementation choices, architectural trade-offs, technology selections | Permanent |
procedures | Step-by-step workflows, build processes, deployment sequences | Permanent |
principles | Coding standards, design rules, constraints that guide future work | Permanent |
incidents | Bugs encountered, root causes, and their fixes | Temporary or permanent |
preferences | User preferences, communication style, naming conventions | Permanent |
Memory never stores secrets, API keys, passwords, raw transcripts, or chain-of-thought reasoning. Only durable, concrete facts are persisted.
Recall: Context Injection
When an execution starts, the recall pipeline queries both memory scopes using the ticket description as a search query. Matching records and session snippets are assembled into a context brief that is injected into the agent's system prompt.
Ticket description and context are used as the recall query
FTS5 full-text search scores and ranks matching records and session chunks
Top results from both project and assistant scopes are merged into a single context brief
The brief is injected into the agent prompt as prior context, with source references and relevance scores
Recall is automatic. You do not need to manually select which memories to include — the system retrieves the most relevant context for each execution based on the task at hand.
Record Storage
Records are stored as individual Markdown files with YAML frontmatter, organized by category. The search index is an SQLite database with FTS5 enabled for fast full-text search.
Each record file contains structured frontmatter (category, creation date, source, aliases, search keywords) followed by the record content. Records are human-readable and can be edited directly in any text editor.
Search & Retrieval
Memory search uses SQLite FTS5 for ranked full-text search across records and indexed session chunks. Results are scored by relevance and returned with source references so you can trace any recalled fact back to its origin.
What gets searched
- Records — durable facts extracted from past sessions (decisions, procedures, etc.)
- Session chunks — indexed segments from past execution transcripts
- Ticket content — indexed ticket descriptions and notes
Recall output formats
| Format | Use case |
|---|---|
snippets | Compact ranked list of matching text fragments with scores |
prompt | Pre-formatted context ready for injection into an agent prompt |
json | Structured JSON output for programmatic consumption |
Managing Records
While extraction is automatic, you have full manual control over records. You can add, update, reclassify, archive, or delete any record.
| Operation | Description |
|---|---|
record add | Create a new record in a specific category and scope |
record update | Modify the content or metadata of an existing record |
record reclassify | Move a record to a different category |
record archive | Soft-remove a record from recall results without deleting the file |
record delete | Permanently remove a record |
record list | List all records, optionally filtered by category |
record get | Retrieve the full content of a specific record by ID |
You can also ask any agent to add a memory record during a session. Tell the agent what to remember, and it will create the appropriate record with the right category and scope.
Compounding Knowledge
Memory improves agent performance over time. Each completed execution potentially adds new records, and every future execution benefits from the growing knowledge base.
First sessions
Agents start with minimal context. They may rediscover patterns, ask about conventions, or make decisions that need correction.
After 10+ sessions
Agents recall project conventions, known pitfalls, and your preferences. Common mistakes stop repeating. Build procedures are followed without prompting.
Mature projects
Hundreds of records across categories give agents deep project awareness. Incidents are avoided because fixes are already known. New agents on the same project inherit the full knowledge base immediately.
Memory is a shared team resource at project scope. When one agent learns something, every agent on the project benefits on their next execution.