Memory model

AgentDesk's shared brain is built in layers. Raw activity is retained for provenance, useful outcomes are distilled into concise memory, and project work is organised into use cases and items. Every layer is scoped per client and project, so teammates and tools share context without leaking it across projects.

The backend database is the authoritative store. Markdown files—including the .okf/ bundle—are generated projections designed for people, Git and AI tools.

Layer 1 — Mirror (raw evidence)

AgentDesk captures activity verbatim:

• Prompts and responses from CLI and IDE sessions.
• Commits, including author, session, changed symbols and complexity data.
• Tool observations — a compact record per agent tool call (tool name, target file or command head, outcome) captured by the PostToolUse hook in Claude Code and Codex. Payloads are never stored. A client-side privacy filter redacts secret-looking strings (API keys, bearer tokens, credentials, private-key blocks) before anything leaves the developer's machine, and the server applies a second redaction net. Identical observations deduplicate within a five-minute window.
• Messages and larger events, such as Slack activity or meeting summaries when connected.
• Code observations, including per-file churn and hotspots.

Mirror records keep the link between a request, the session that handled it and the resulting commit. They are audit evidence, not the context injected into every model call.

Layer 2 — Events, summaries and current facts

At session end, AgentDesk distils raw exchanges into session summaries and structured events: decisions, conventions, components and other durable facts. Useful records can carry vector embeddings for semantic search.

Facts represent current project state. When code proves that a fact changed—for example, a backend moved from Python to Rust—the old value is invalidated and the current value replaces it in generated project context. A full Rescan reconciles facts and open work against the codebase, and reversibly archives records proven obsolete.

This makes questions such as “Why did we choose Postgres?” or “What changed in authentication last week?” answerable without loading months of raw conversation.

Layer 3 — Work items and use cases

Accumulated prompts, commits, messages and imported documents are classified into a two-level backlog:

Use case (US)
 ├─ Feature (FE)
 ├─ Bug (BU)
 ├─ Task (TA)
 ├─ Policy (PO)
 └─ Requirement (RE)

Items move through open → pending → in-progress → review → done. Classification produces deduplicated drafts first; a person approves them before they receive stable IDs. Approved items are searchable alongside facts. A parent use case cannot be completed while any child is still open.

“What was done” and provenance

The solve skill records a timestamped delivery entry against the relevant item and its parent use case. An entry can include the outcome, tests, review result, score, duration and commit. Explicit commit references such as fixes BU3001 are reconciled into the same history.

This gives each use case a durable answer to:

• What was implemented?
• When was it done?
• Which item and commit delivered it?
• What verification was performed?

Repeated hook delivery is idempotent: the same commit-backed entry is not added twice.

Documents and editable use cases

The documents area contains different kinds of content:

documents/
├── product-spec.md       # source document; can be mapped into work
├── use_cases/            # editable, managed use-case Markdown
└── .okf/                 # generated, read-only interoperability bundle

Files under use_cases/ are designed for people and agents to edit and may be organised into subfolders. AgentDesk keeps their items and “What was done” sections aligned with backend state.

Files under .okf/ are generated from backend memory. They are visible in the Documents view but excluded from document intake and AI mapping, so they cannot create duplicate use cases.

Open Knowledge Format (OKF)

AgentDesk exports an OKF v0.1-compatible knowledge bundle. It follows the Git-native, Markdown-oriented approach associated with LLM Wiki: give any model a small index and linked concepts instead of injecting an entire raw history.

Typical contents are:

.okf/
├── index.md              # current project overview and navigation
├── log.md                # bounded activity counts and provenance notes
├── manifest.json         # version, generation time and managed file list
├── facts/                # current durable project facts
├── sessions/             # recent concise session summaries
├── use_cases/            # read-only use-case summaries and work logs
└── events/recent.md      # recent high-value events

The bundle is intentionally bounded: it does not copy every raw prompt or response. Use the MCP server when an agent needs audited drill-down into raw history.

How OKF stays updated

AgentDesk regenerates the bundle from backend state after memory extraction, work-log changes and commit reconciliation. The desktop reconciles the returned manifest into the local .okf/ folder and removes stale generated files.

Commit .okf/ to your repository if you want collaborators and AI tools without an AgentDesk connection to receive the same project overview. Do not edit it by hand—generated changes will overwrite manual edits. Update facts, use cases or work items through AgentDesk, MCP or the editable use_cases/ files instead.

Retrieval engine — hybrid search

Memory recall fuses three independent ranking signals rather than trusting any single score:

1. Semantic — vector similarity (pgvector) over embedded facts, summaries and work items.
2. Keyword (BM25-class) — PostgreSQL full-text search with stemming, length-normalised ranking and a curated synonym expansion, so db migration also matches database. Exact error messages, file names and identifiers rank well here.
3. Relationship graph — facts connected to the direct matches through shared touched files join the candidate set, ranked by overlap and recency. The graph is derived from relations AgentDesk already records; there is no separate graph store to maintain.

The rankings merge with Reciprocal Rank Fusion, which is robust to incomparable score scales, and results are session-diversified: one long session contributes at most three results, so a burst of similar activity cannot crowd out the rest of project history.

Retrieval quality is measurable: a benchmark harness scores recall@5 against a labelled query set and can gate CI, so search upgrades are verified rather than assumed.

How tools share memory

All layers sit behind the MCP server, the desktop UI and generated files:

• Claude Code, Codex or Gemini work is captured, summarised and classified.
• An IDE asking “What is the auth convention?” receives the current fact through search_memory.
• A teammate opening the project sees the same facts and backlog.
• A disconnected CLI can read .okf/index.md and follow links to the relevant fact or use case.

Embeddings need a provider key

The semantic signal depends on an embeddings provider such as OpenAI. Without one, AgentDesk still ranks with the full keyword + graph signals — recall degrades gracefully instead of falling back to bare substring matching. See Models & keys.

Next: Skills →