Project Memory

Not a markdown file. Not a vector database. A persistent knowledge base with typed facts, semantic search, episodic narratives, a knowledge graph with directional edges, working memory pinning, and automatic compaction — all surviving across sessions.

Architecture

Facts — individual knowledge atoms stored with section, confidence, and timestamp. Sections: Architecture, Decisions, Constraints, Known Issues, Patterns & Conventions, Specs, Recent Work.
Episodes — session narratives that capture goals, decisions, sequences, and outcomes. What happened and why.
Knowledge Graph — typed edges between facts: depends_on, contradicts, enables, replaces, motivated_by.
Working Memory — pinned facts that persist across context compaction. Priority injection into every turn.
Archive — superseded or stale facts. Searchable but not injected into context.

Agent Tools

Tool	Purpose
`memory_recall(query)`	Semantic search — returns ranked facts by relevance × confidence
`memory_query()`	Load all active facts (expensive — prefer `memory_recall`)
`memory_store(section, content)`	Persist a new fact
`memory_supersede(fact_id, content)`	Atomically replace a fact with an updated version
`memory_archive(fact_ids)`	Archive stale facts (removed from active context)
`memory_episodes(query)`	Search session narratives for episodic context
`memory_focus(fact_ids)`	Pin facts to working memory (survives compaction)
`memory_release()`	Clear working memory buffer
`memory_connect(source, target, relation)`	Create a typed edge in the knowledge graph
`memory_compact()`	Trigger context compaction to free context window
`memory_search_archive(query)`	Search archived (superseded/stale) facts — not injected into context but still queryable
`memory_ingest_lifecycle()`	Batch-import recent design-tree decisions and resolved questions into the memory store

Lifecycle

Store — agent discovers something important, stores a fact
Recall — on future turns, agent searches for relevant facts by query
Supersede — when understanding changes, old fact is replaced atomically
Connect — relationships between facts are recorded as graph edges
Archive — stale facts are moved to archive (still searchable, not injected)
Compact — when context fills, older conversation is summarized; pinned facts survive

Auto-Ingestion

Two automatic memory flows run without explicit tool calls:

Lifecycle decisions — when design_tree_update(add_decision) or a status transition to resolved/decided/implementing fires, the decision is automatically persisted to the Decisions memory section via the bus. No memory_store call needed.
Session episodes — at session close, a template episode is automatically written (title, turn count, tool call count, duration) and tagged auto. Searchable via memory_episodes in future sessions for continuity context.

Operator Commands

/memory       # Show memory stats: facts, episodes, working memory
/compact      # Trigger context compaction manually
/note [text]  # Quick-capture a note (persists across sessions)
/notes        # Show pending notes

Storage

Facts are stored as one JSON object per line in the project's memory directory. This file is git-tracked with merge=union in .gitattributes, allowing multiple branches to add facts without merge conflicts. SQLite databases are gitignored and rebuilt from the JSONL source of truth.