Skip to main content

Memory model

AgentDesk's shared brain is built in three layers. Raw activity flows in at the bottom, gets distilled into durable facts in the middle, and is organised into a backlog at the top. Every layer is scoped per client and project, so teammates and tools share context without leaking it across projects.

Layer 1 — Mirror (raw capture)​

Everything that happens, captured verbatim:

  • Prompts — every prompt and response from your CLI and IDE sessions.
  • Commits — every git commit, with symbol-level diffs (tree-sitter) and complexity scores (lizard).
  • Code files — per-file change frequency and churn.

This is the source of truth — nothing is interpreted yet.

Layer 2 — Events (durable facts)​

An AI pass distils the raw mirror into structured facts — decisions, conventions, components and session summaries. Each fact carries a vector embedding for semantic search and bi-temporal validity (when it became true, when it stopped), so superseded facts are kept in lineage rather than lost.

This is what makes "why did we choose Postgres over Mongo?" answerable months later, by any tool.

Layer 3 — Work Items (classified backlog)​

Activity is classified into a two-level backlog:

Use case (UC)
 ├─ Feature (FE)
 ├─ Bug (BU)
 ├─ Task (TA)
 └─ Requirement (RE)

Items move through a lifecycle (open → pending → in-progress → review → done). Approved items get embeddings too, so the backlog is semantically searchable alongside the facts. A parent use case can't be completed while any child is still open.

How tools share it​

All three layers sit behind the MCP server and the web UI. So:

  • Claude Code commits → captured in Mirror → distilled into Events.
  • Your IDE asks "what's the auth convention here?" → search_memory returns the Event.
  • A teammate opens the same project → sees the same facts and backlog.

Semantic search runs cosine similarity across the Events and Work-Item layers, so recall is by meaning, not keyword.

Embeddings need a provider key

Semantic search depends on an embeddings provider (e.g. OpenAI). Without one, AgentDesk falls back to keyword matching, which is weaker. See Models & keys.

Next: Skills →