Skip to content

memory-system-guide.md

Latest commit

 

History

History
497 lines (316 loc) · 20.6 KB

memory-system-guide.md

File metadata and controls

497 lines (316 loc) · 20.6 KB

Memory System Guide — AITEAM-X

For: AITEAM-X dashboard users
Updated: 2026-03-24
Version: 3.0

What is the memory system?

By default, every time you open a conversation with an agent, it starts from scratch — remembering nothing from earlier discussions. The memory system fixes that.

It automatically records what happens in each session and injects that context back into the agent the next time you talk to them. The result: the agent remembers past decisions, open tasks, and problems already solved — without you having to explain everything again.

What does the agent remember?

Each agent has its own memory vault, organized into five categories:

Category What it stores Examples
Decisions Technical or project choices that were made "We chose SSE instead of WebSockets", "Naming convention: kebab-case for agent IDs"
Lessons Fixed bugs, solved problems, insights discovered "spawn() timeout does not work on Windows — use manual setTimeout", "The tag must be embedded in the text to survive updateEntry()"
Handoffs Summary of what was done last session and what comes next "We implemented the /sleep endpoint and the badge component. Next: integration tests"
Tasks Open items in checklist format "- [ ] Review handoffs after critical sessions", "- [x] Migrate handoff flow"
Project General context — stack, architecture, goals "Next.js 15 App Router, no Tailwind, VT323 pixel font, Cursor Agent CLI required"

Besides each agent’s individual vault, there is a shared _project.md file, injected into all agents. That is the right place for information any agent needs to know.

How is memory populated?

There are three ways:

1. Automatically when closing a session

When you close an agent’s chat window (× on the bubble or in the drawer), the system:

  1. Saves a conversation checkpoint
  2. Generates an automatic handoff from the last 6 messages
  3. Saves the handoff in the vault with tags auto-handoff and session-close

The next time you open a session with that agent, they receive that handoff as context.

2. Manually via Memory Vault

Click the 🧠 icon in the top bar to open Memory Vault. From there you can:

  • View all memories per agent by category
  • Create new entries manually
  • Edit or delete existing entries
  • Search free text (BM25 search)

3. Via script for historical conversations

To import decisions and lessons from old conversations that have not been processed yet:

node scripts/import-conversations.mjs

The script analyzes conversation text using keywords and distributes relevant snippets into the correct vault categories.

Session lifecycle

Understanding the full cycle helps you know what the agent will remember — and what might be lost.

Open chat
    │
    ├─ [auto-save 30s] → conversation saved to .memory/conversations/{agentId}.json
    │
    ├─ [checkpoint 30s] → snapshot saved to .vault/checkpoints/{agentId}.json
    │
    ├─ [close via ×]
    │       │
    │       ├─ 1. Final checkpoint saved
    │       ├─ 2. Handoff generated (last 6 messages)
    │       ├─ 3. Decisions and lessons extracted from conversation (PT+EN heuristic)
    │       └─ 4. Everything saved to vault → injected on next session
    │
    ├─ [unexpected close (tab/browser)]
    │       │
    │       └─ sendBeacon saves checkpoint + conversation (handoff NOT generated)
    │
    └─ [next session]
            │
            └─ Automatic context injection (see section below)

The automatic checkpoint every 30s protects conversation content. Even if the window closes unexpectedly, history is preserved on disk for up to 7 days.

How context is injected on the next session

This is the core mechanism: exactly what the agent receives when you start a new conversation.

What is injected

  1. Project context — full contents of _project.md
  2. Last session handoff — the most recent summary, highest priority
  3. Relevant decisions — up to 3 decisions selected by text search (BM25) based on what you are asking
  4. Relevant lessons — up to 2 lessons selected the same way
  5. All open tasks — items with [ ] not marked done
  6. Recovery snapshot — if there is a valid checkpoint, the last 3 messages are included

How relevance is calculated

The system uses BM25 (text search) to select the most relevant entries. BM25 compares your message text with stored memory content and returns the most similar ones.

In practice: if you ask to "review the authentication flow", the system injects decisions and lessons that mention authentication, session, tokens — not memories about CSS or deploy.

Token budget

Injected context has a limit of 2,000 tokens (estimated as text_length / 4). If selected memories exceed that limit, the system prioritizes in this order:

  1. Handoff — always included, highest priority
  2. Open tasks — always included
  3. Relevant decisions — trimmed if needed
  4. Relevant lessons — trimmed first among BM25 results
  5. Project context — included last

What this means in practice

The agent does not remember everything — it remembers what is most relevant to the current conversation. For specific topics you want guaranteed recall, use the right vault category (e.g. important decisions under "Decisions", not under "Project").

The _project.md file — shared memory

The file .memory/_project.md is special: it is injected into all agents, in every session.

When to use it

Use _project.md for information any agent needs to know without asking:

  • Project tech stack
  • Team code conventions
  • Current sprint goals
  • Architectural decisions that affect everyone
  • Environment constraints (e.g. "deploys only on Fridays")

What not to put there

  • Agent-specific information — use the individual vault
  • Tasks — use the "Tasks" category in each agent’s vault
  • Conversation history — that lives in checkpoints

Example of a well-written _project.md

# AITEAM-X project

**Stack:** Next.js 15 App Router, React 19, TypeScript, no Tailwind  
**Font:** VT323 (pixel art), styles in app/globals.css  
**Required runtime:** Cursor Agent CLI

## Conventions
- Agent IDs: kebab-case (bmad-master, game-designer)
- API routes: REST for CRUD, SSE for streaming

## Current sprint
- Focus: memory system v3.0
- Documentation in /docs required for new features

Tip: Keep _project.md under ~500 words. A very long file can hit the token budget and push more relevant information (decisions, handoffs) out of injected context.

Memory Vault — visual interface

Memory Vault (🧠 in the top bar) is the main UI for managing memories.

Navigation

  • Agent selector (top): choose which agent to view
  • Category tabs: Decisions / Lessons / Handoffs / Tasks / Project
  • Search field: real-time BM25 search (300ms debounce, up to 15 results)

Creating entries manually

  1. Select the agent
  2. Select the category
  3. Click + New entry
  4. Enter content (markdown supported)
  5. Save

Manual entries persist until you delete them.

Editing entries

Click the pencil icon next to the entry. Content becomes inline-editable. Save with Enter or the check icon.

Deleting entries

Click × next to the entry. Deleted entries cannot be recovered.

Tags — how they work

Each vault entry can have tags associated with them. Tags:

  • Are extracted automatically from text (words preceded by #)
  • Appear next to the entry in Memory Vault
  • Affect BM25 search: a memory tagged #auth can show up in authentication-related searches even if the main text does not mention it explicitly

System tags

Tag Source Meaning
#auto-handoff Frontend Handoff generated automatically when closing session
#session-close Frontend Marks entries created on session close
#compacted Compaction Entry created during automatic compaction
#auto-extract Compaction Insight extracted by heuristic from trimmed conversations

Best practices by category

Decisions

  • Be specific: "We chose SSE" is vague. Better: "Adopt SSE instead of WebSockets — deploy environment does not support persistent bidirectional connections."
  • Include the reason: A decision without context is hard to revisit. Always explain why.
  • One decision per entry: Grouping many decisions in one entry hurts BM25 retrieval.
  • Use relevant hashtags: #sse #architecture #deploy help recover the decision in future contexts.

Lessons

  • Focus on the problem, not only the solution: Start with the symptom: "spawn() on Windows does not report a reliable exit code when the process is killed via timeout." Then the solution.
  • Include where it applies: "On Windows", "in production", "when the config file is missing" — context for when the lesson applies.
  • Record anti-patterns: If you found a bad solution, record it too so it is not repeated.

Handoffs

  • The system generates automatically: Closing the session with × creates a handoff from the last 6 messages.
  • Create manually for critical sessions: If the session was very important or long, open the vault and add a more detailed manual handoff.
  • Include the next step: "We implemented X. Next: Y." is more useful than only "We implemented X."

Tasks

  • Use the standard format: - [ ] task description (open) / - [x] description (done)
  • Mark when done: Tasks with [ ] appear in all future sessions for that agent. If irrelevant, delete or mark [x].
  • One action per task: "Implement X and Y and test Z" should be three separate tasks.

Project

  • Stable information: The Project category is for context that changes rarely.
  • Do not duplicate _project.md: If something matters for all agents, put it in _project.md. If it is agent-specific, use that agent’s Project category in the vault.

Best practices for better performance

1. Keep _project.md lean

Project context is injected in every session for every agent. A long file consumes token budget that could go to more relevant decisions and lessons. Target: under 500 words.

2. Close sessions with the × button

Closing via × is the only path that generates automatic handoffs. Closing the tab or browser only saves the checkpoint via sendBeacon — no handoff.

3. Review handoffs for important sessions

Automatic handoff is based on the last 6 messages. If the conversation was long and critical decisions were in the middle, the handoff may miss them. Add a complementary manual handoff in the vault.

4. Use tags strategically

Tags like #api, #performance, #bug connect memories so BM25 can retrieve them. When the agent receives "optimize API performance", memories with #api and #performance are more likely to be injected.

5. Clean up completed tasks

Tasks with [ ] are injected in every session. A long open-task list consumes tokens and clutters context. Mark [x] or delete when done.

6. One idea per entry

Granular entries are retrieved more precisely by BM25 than entries mixing several topics. "We chose SSE" and "We adopted kebab-case for IDs" should be separate entries.

7. Let compaction run

The system runs automatic compaction every 10 minutes while the dashboard is open. It:

  • Clears checkpoints older than 7 days
  • Trims long conversations (> 20 messages)
  • Consolidates categories with more than 30 entries

To force manually:

curl -X POST http://localhost:3000/api/memory/compact

8. Monitor active agents’ vaults

Frequently used agents accumulate memories quickly. Periodically check for:

  • Duplicate or contradictory entries
  • Whether old handoffs are still relevant
  • Lessons that were incorporated into code (and can be removed)

Automatic compaction

Over time the vault grows, conversations get long, and old checkpoints use space. Automatic compaction addresses this without manual cleanup.

What compaction does

Step What it does Result
Expired checkpoints Removes checkpoints older than 7 days Disk space freed
Long conversations Trims conversations with more than 20 messages, keeps only the most recent Decisions and lessons extracted from removed messages are saved to the vault
Overfull vault Consolidates categories with more than 30 entries — keeps the 20 newest and summarizes the rest Leaner vault without losing information
Search index Rebuilds the BM25 index after changes Search stays current
Legacy files Removes migration .bak and flat .md files already migrated Disk cleanup

Frequency

The dashboard runs compaction automatically every 10 minutes. On load it also checks whether the last compaction was more than 10 minutes ago — if so, it runs immediately.

What happens to messages removed from long conversations?

Trimming is not destructive. Before removing old messages, the system:

  1. Analyzes text for decision patterns (e.g. "we decided", "we will use", "opted for") and lesson patterns (e.g. "we learned", "important", "we discovered")
  2. Saves found insights as vault entries with tags #compacted and #auto-extract
  3. Generates a summary (handoff) of the last removed messages with tag #auto-handoff

Those entries are marked in the vault so you know they came from compaction, not manual entry.

To check the last compaction result

curl http://localhost:3000/api/memory/compact

Safety

Compaction can only run from localhost. Requests from external IPs get 403 Forbidden.

Case studies

Case 1: Bug fixed yesterday, forgotten today

Situation: You spent an hour on Friday finding that Node.js spawn() does not fire the close event with a reliable exit code on Windows when the process is killed by timeout. You fixed it with a timedOut boolean + manual setTimeout + proc.kill(). On Monday you open a new session and no longer remember why the code looks that way.

With the memory system:

  • Closing Friday’s session (×) generates a handoff automatically
  • You add a manual vault lesson: "spawn() close on Windows does not report a reliable exit code when the process is terminated via timeout. Solution: manual setTimeout + timedOut boolean + proc.kill()."
  • On Monday, opening a new session about the same code injects that lesson via BM25
  • The agent understands context immediately without you re-explaining

Tip: For important technical lessons, add them manually to the vault — more reliable than automatic handoff alone.

Case 2: Forgotten architecture decision

Situation: Three weeks ago the team decided not to use WebSockets and to adopt SSE for streaming because the deploy environment does not support persistent bidirectional connections. Today a new developer proposes WebSockets.

With the memory system:

  • The decision was recorded under "Decisions" for bmad-master: "Adopt SSE instead of WebSockets — deploy environment does not support persistent bidirectional connections. #sse #architecture"
  • Starting a session about streaming, BM25 retrieves that decision and injects it
  • The agent proactively mentions the constraint

Case 3: Tasks spanning multiple sessions

Situation: You are implementing a large system over several weeks. Each session makes partial progress.

With the memory system:

  • Each closed session generates an automatic handoff
  • Open tasks stay visible: "- [ ] Implement processPending() with retry", "- [ ] Add --dry-run flag"
  • Opening the next session, the agent knows where you left off and what is left
  • When a task is done, mark [x] — it stops appearing in future sessions

Case 4: Project context for a new agent

Situation: You need to talk to game-designer for the first time. They know nothing about the project.

With the memory system:

  • _project.md contains stack, conventions, project constraints
  • It is injected automatically on the first session with any agent
  • The agent understands the environment immediately
  • You do not need to explain context on every new conversation

Troubleshooting

The agent is not remembering something important

Likely cause: The memory was never created, or is not relevant enough for BM25.

What to do:

  1. Open Memory Vault (🧠)
  2. Check the memory exists in the right category
  3. If missing: create it manually
  4. If present but unused: rewrite to include keywords more specific to the context where you expect injection
  5. Add relevant tags to widen search coverage

Automatic handoff was not generated

Likely cause: The session ended unexpectedly (not via ×).

What to do:

  • Always close sessions with ×
  • If the session already passed: create a manual handoff in the vault summarizing what was discussed

The agent is getting outdated information

Likely cause: An old memory in the vault still has incorrect information.

What to do:

  1. Open Memory Vault
  2. Search for the outdated term
  3. Edit or delete the old entry
  4. Create a new entry with correct information

An agent’s vault feels too heavy

Likely cause: Many sessions without recent compaction.

What to do:

  1. Check whether the dashboard has been open recently (automatic compaction needs an active dashboard)
  2. Force compaction: curl -X POST http://localhost:3000/api/memory/compact
  3. Or review manually: delete old handoffs, merge similar lessons
  4. Completed tasks ([x]) can be deleted — they are no longer injected but clutter the UI

_project.md is being truncated

Likely cause: The file is too long and exceeds the 2,000-token budget.

What to do:

  1. Review _project.md and remove information not relevant to all agents
  2. Move agent-specific context to that agent’s vault
  3. Keep the file under ~500 words (~2,000 characters)

BM25 search returns weak matches

Likely cause: The index may be stale after manual filesystem edits.

What to do:

  1. Force compaction (rebuilds index): curl -X POST http://localhost:3000/api/memory/compact
  2. Ensure entries use consistent vocabulary — BM25 is sensitive to exact words

What is NOT stored automatically

  • Files and images sent in the conversation
  • Sessions closed without × — closing the tab or browser saves the checkpoint via sendBeacon, but does not generate a handoff
  • Tool call content — if the agent used a tool, the tool result is not extracted as memory
  • Internal messages — messages marked internal (system-generated) are not saved in checkpoints or used for handoffs

FAQ

The agent is not remembering something important — what do I do?
Open Memory Vault (🧠), go to the right category, and add the entry manually. It will be injected on the next session if relevant to BM25, or always if it is a handoff or open task.

Can I wipe everything and start fresh?
Yes — delete entries via Memory Vault. _project.md can be edited as plain text. Checkpoints live under .memory/.vault/checkpoints/ and can be deleted manually.

Does one agent’s memory affect other agents?
Not directly. Each agent has an isolated vault. The only shared memory is _project.md.

How do I know what the agent will get next session?
The agent receives: latest handoff + decisions/lessons relevant to your command + all open tasks + _project.md. You can inspect those entries in Memory Vault before starting the conversation.

How many handoffs are kept?
Only the most recent handoff is injected into context. Older handoffs remain in the vault for reference but are not injected automatically — unless relevant in BM25 search.

Can compaction lose important information?
Compaction tries to extract decisions and lessons from removed messages using pattern matching. For truly critical information, record it manually in the vault — the most reliable way to ensure the agent remembers.

What if the dashboard stays closed for a long time?
Checkpoints expire after 7 days. Vault memories (decisions, lessons, handoffs, tasks, projects) persist indefinitely. Compaction only runs while the dashboard is open — after long idle periods, the first open may trigger a heavier compaction.

Can I edit _project.md directly in a text editor?
Yes. The file is at .memory/_project.md as plain markdown. Changes apply on the next session for any agent.