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.

Semantic recall uses the configured Ollama embedding endpoint when reachable. Builds compiled with local-embeddings can also load a local ONNX sentence-transformer model; without either backend, memory falls back to FTS5 keyword search.

Memory is an optional managed service. If it is unavailable at startup, memory tools and status remain visible with an explicit unavailable result. Durable-memory context is omitted, while unrelated context and the rest of the session continue without a direct-storage fallback.

A separate optional managed context/compaction planner selects deterministic history windows. If it is unavailable, ordinary context assembly and unrelated turns continue, while manual or automatic managed compaction planning reports unavailability instead of calling a direct planner.

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_query(query, ...)`	Query stored memory with structured filters
`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
/context 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. Omegon exposes a renderer-neutral memory and federation status projection that classifies one-off, Git, lifecycle, and federation contexts while treating Git-tracked JSONL facts as the cross-checkout memory authority.

Embedding Backends

Backend	How it is selected	Fallback
Ollama embeddings	Configured profile or `OMEGON_EMBED_URL` / `OMEGON_EMBED_MODEL`	Falls through if the endpoint probe fails
Local ONNX	Binary built with `local-embeddings` and model files at `~/.config/omegon/models/all-MiniLM-L6-v2/`	Falls through if files are missing or model load fails
FTS5	Always available	Keyword recall only

The local ONNX path expects model.onnx and tokenizer.json. Override the model name with OMEGON_EMBED_LOCAL_MODEL or the exact directory withOMEGON_EMBED_MODEL_DIR.