Memory

Memory is what makes Crew feel like it knows you. New sessions inherit preferences, project context, and learned corrections from every session that came before — without replaying old conversations token by token.

There are six independent memory layers, each with a specific purpose.

User habits, tool preferences, communication style. Replaced wholesale by the consolidator every 30 messages — not append-only.

• Source: ~/.kiro/crew/workspace/memory/preferences.md
• Injected every new session
• Cap: 4,250 chars

Example:

- Prefers Slack for communication and monitoring
- Uses standard Python build system (setuptools/pip)
- Prefers deep code analysis with hidden information uncovered
- Wants diagrams in documentation for complex flows

CRs, packages, branches, status. Same lifecycle as preferences.

• Source: ~/.kiro/crew/workspace/memory/projects.md
• Injected every new session
• Cap: 6,400 chars

• Source: ~/.kiro/crew/workspace/memory/history/
• Updated on 3-hour idle per session
• Cap: 26,600 chars
• Pruned daily via the heartbeat service

Structured facts stored in SQLite. Always on — embeddings activate automatically once the model downloads.

• Storage: SQLite semantic_memory table + optional FAISS index
• Key prefixes: pref.*, project.*, user.* (plus user-configurable extras)
• Cap: 12,000 chars
• Retrieval: hybrid 0.6 × vector_score + 0.4 × keyword_score (keyword-only fallback if the embedding model hasn't downloaded yet)

Example entries:

user.dev_desktop_host_current: dev-host.example.com
project.kirocrew.zoom_fix_implemented: True
pref.prefers_configregions_over_null_guards: True

Confidence gating prevents hallucinated writes. LLM writes require confidence ≥ 0.8. User-explicit writes always win regardless of confidence. On conflict, higher confidence wins; same confidence → newer wins.

Short text snippets capturing specific past events — "fixed the zoom bug by adding CSS custom properties", "user prefers pytest-asyncio strict mode". Think of them as searchable bookmarks into past conversations.

• Storage: SQLite episodic_memories table + optional FAISS index
• Text length: 10–2,000 chars per entry
• Dedup: FAISS cosine > 0.88 rejects near-duplicates
• Cap: 3,000 chars, top-8 results per query
• Max entries: 10,000 (lowest-importance oldest pruned when exceeded)

Search uses decay scoring with MMR diversity reranking (Jaccard-based, λ=0.6) to avoid redundant results. A two-stage filter first drops irrelevant matches on raw cosine, then decay-adjusted scoring ranks the survivors.

User-taught rules that override default behavior. Created when you say "always do X" or when a correction pattern is detected in a conversation.

• Storage: lesson.<md5hash> semantic entries (confidence 1.0)
• Dedup: substring match + topic overlap (>50% keyword → replace)
• Cap: 37,250 chars, max 50 lessons
• Injected as a distinct [Learned corrections] block

Example:

- Dashboard auto-scroll should only trigger when the user is near bottom (within 80px).
- Task Runner resets the agent session after each step — the agent can't carry context forward.

User Message
    │
    ├──► learn_add MCP tool ──► write_lesson() ──► Immediate lesson save
    │    (user says "remember X" or agent is corrected)
    │
    ├──► 30 messages ──► HistoryConsolidator (prefs path)
    │                    ├── Updates preferences.md (wholesale replace)
    │                    ├── Updates projects.md (wholesale replace)
    │                    └── Extracts semantic entries (max 20)
    │
    ├──► 3h idle ──► HistoryConsolidator (history path)
    │                ├── Appends to history/{date}.md
    │                ├── Extracts episodic entries (max 10)
    │                └── Extracts implicit lessons (corrections without "remember")

The prefs path does not advance the persisted last_consolidated marker — history consolidation always covers all messages, even if prefs consolidation fired earlier.

• Explicit — user says "remember to always use pytest-asyncio strict mode" → saved immediately via learn_add
• Implicit — user corrects the agent without saying "remember" (e.g., "No, don't cache that — the value changes per request") → extracted during history consolidation

Both go through write_lesson() which provides substring dedup and topic-overlap dedup.

Three independent decay mechanisms prevent stale memories from consuming context.

Older history progressively loses detail (see table above). "Something happened" markers eventually replace full entries, then get dropped from context but kept on disk as backup, then are deleted altogether at 365 days.

score = cosine_sim × (0.7 + 0.3 × importance) × exp(-0.03 × days_old)

• cosine_sim — semantic relevance to the current query
• 0.7 + 0.3 × importance — high-importance memories decay slower
• exp(-0.03 × days_old) — exponential decay: 50% at ~23 days, 10% at ~77 days

At 10,000 entries the lowest-importance, oldest ones are pruned first.

1. Lessons (user-explicit, confidence 1.0)
2. Semantic memory (user-explicit writes)
3. Semantic memory (LLM writes, confidence ≥ 0.8)
4. Preferences / projects (consolidation-generated)
5. Episodic memory (relevance-scored fragments)
6. History (time-decayed summaries)

Lessons win the tie because they're injected in a distinct [Learned corrections] block that reads "ALWAYS follow these. They override default behavior."

The context builder assembles all sources into the prompt. Different content is injected at different times.

The same memory store is shared across every channel, but recording behavior varies:

Security in observe mode. Only messages from authorized users (owner + allowlist) are recorded. Non-authorized messages are silently dropped to prevent prompt injection.

The CLI is the fastest path to add a lesson:

kirocrew learn add "always use TypeScript over JavaScript"
kirocrew learn add "prefer pytest over unittest" --category tool
kirocrew learn list
kirocrew learn remove "prefer pytest"

The learn_add MCP tool is the same interface exposed to the LLM — when the agent recognizes a correction, it calls the tool itself.

The dashboard exposes memory management surfaces:

• Memory Graph Explorer — visualize semantic memory relationships (vis.js)
• Skills / Lessons CRUD — add, edit, remove from the browser
• Knowledge Library — ingest external docs into a curated store (separate from episodic/semantic memory)

Distinct from the automatic memory layers, the Knowledge Library is a curated document store for external content — files, folders, or URLs you want the agent to be able to search.

• Sources: local files, local folders (recursive scan), URLs (fetched at ingest)
• Ingestion pipeline: chunking, entity extraction, embedding generation
• Search: local_knowledge_search MCP tool with strict trigger rules and a confidence threshold

The library is a built-in surface in the dashboard sidebar — not an App Store app.

Memory is included in kirocrew snapshot:

kirocrew snapshot                     # ~/.kiro/crew/snapshots by default
kirocrew restore snapshot.tar.gz      # auto-detects replace vs merge

Snapshots include memory.db (episodic + semantic), memory_index.db (FTS5 index), and workspace/memory/ (structured markdown). See Snapshot & restore for the full model.