Project Memory

Annodex uses a dual-layer memory model (Phase 1): durable markdown files injected into every new thread, plus a JSONL working memory store the agent can read and write through MCP tools.

Overview

Passive injection (thread start)     Working memory (agent tools)      Promotion (you or agent)
────────────────────────────────     ────────────────────────────      ────────────────────────
~/.config/annodex/SOUL.md            retain → JSONL entries            → MEMORY.md
~/.config/annodex/HARNESS.md         recall → lexical search            → CONTEXT.md
{project}/AGENTS.md                  reflect → synthesize answer
{project}/MEMORY.md
{project}/CONTEXT.md

Working memory is not vector search in Phase 1 — recall ranks entries by lexical match, importance, and recency.

Passive injection

When annodex starts or resumes a Codex thread, buildSystemPrompt() loads context files in this order:

1. Annodex runtime rules (in code) — tool authorization and safety baseline
2. Global SOUL.md — persona, tone, working style (neutral default seeded on first start)
3. Global HARNESS.md — behavioral constraints and output rules
4. Project AGENTS.md (or CLAUDE.md) — project-specific instructions
5. Project MEMORY.md — durable analysis log and long-term notes
6. Project CONTEXT.md — stable facts, paths, conventions, assumptions

These files are background continuity, not hard overrides for safety or tool rules. Edit project files (MEMORY.md, CONTEXT.md, AGENTS.md) from the Files panel or your editor. Edit global SOUL.md / HARNESS.md under ~/.config/annodex/ (see Configuration). Changes apply on the next turn that starts a fresh system prompt context.

Lowercase filenames (memory.md, context.md) are detected if the uppercase file is missing.

Working memory store

Per-project JSONL lives under annodex config (not inside the repo):

~/.config/annodex/memory/<sha1(project-cwd)>/entries.jsonl

Override the config root with ANNODEX_CONFIG_DIR — memory follows the same path.

Each line is one record with fields such as:

• content — the fact or note
• importance — 0–1 (higher → more likely to become a promotion candidate)
• memoryType — fact, context, preference, decision, or note
• governance.candidate — none, spark, or project_memory (UI highlights candidates for promotion)

Agent tools (MCP)

Three tools are exposed through the annodex-memory MCP server:

Enable the memory extension

1. Start annodex (the MCP server calls the local HTTP API).
2. Open Settings → Extensions.
3. Add or select the Annodex Memory preset (annodex-memory-mcp).
4. Click Install to Codex (once per machine/user).
5. Enable annodex-memory for the session from the chat bar Extensions control.

On first session start, annodex also registers the extension definition in ~/.config/annodex/extensions.json.

The MCP process uses the Codex workspace cwd as the project key and reads the annodex listen port from ~/.config/annodex/annodex.json (default port 30121).

Tools panel — inspect and promote

Open the Tools tab in the right sidebar (with a project selected):

• Counts by memory type and number of promotion candidates
• Path to the JSONL store (relative to the project when possible)
• Promotion candidates — high-importance or decision/context entries
• Recent memory — latest retained items

Use To MEMORY.md or To CONTEXT.md to append a candidate to the project markdown files. Promotion is idempotent — the same entry is not duplicated if already promoted.

You can also promote programmatically:

POST /api/memory/promote
Content-Type: application/json

{
  "cwd": "/path/to/project",
  "memoryId": "<uuid from working memory>",
  "target": "memory"
}

target may be "memory" or "context".

When to use which file

A practical workflow:

1. Let the agent retain durable facts during analysis.
2. Review candidates in Tools → Memory.
3. Promote vetted items to MEMORY.md or CONTEXT.md.
4. Future threads automatically load the markdown layers at startup.

API reference (local server)

These routes are intended for localhost use alongside the annodex UI and MCP bridge.

Related configuration

See Configuration for path tables and Usage for day-to-day workflow in the workspace.

Roadmap (not in Phase 1)

Future phases may add vector or FTS search, automatic top-K recall at turn start, checkpoints, and sleep-style compression. Phase 1 deliberately mirrors a simple, inspectable JSONL + markdown hybrid.