nimmo/nixos-config
nimmo/nixos-config
Watch
1
0
Fork
You've already forked nixos-config
 0
Code Issues 15 Pull requests Wiki Activity Actions
Page: 24 ADR 004 Engram Durable Agent Memory
Pages
00 Documentation Map and Scope 00 Documentation Standards 00 Start Here and Governance 10 System Atlas 11 Fleet Overview 12 Host Inventory 13 Service Catalogue 14 Network and Access Topology 15 Storage and Data Map 16 Automation and Control Plane 20 Architecture Decisions 21 ADR 001 Electra Hardware Specialisations 22 ADR 002 Workload Placement 23 ADR 003 Network Exposure 23 Project Tracking 24 ADR 004 Engram Durable Agent Memory 24 Security Baseline 25 ADR 005 Auto Update Control Plane 26 ADR 006 Scoped Secret Files 30 Operations and Runbooks 31 Routine Fleet Operations 32 Safe Testing and Deployment 33 Host Provisioning 34 Monitoring and Service Investigation 35 Backup Verification and Partial Restore 36 Full Host Recovery 37 Electra Boot Trust Recovery 38 Secret Editing and Recipient Rotation 39 Auto Update Incident Response 39a Service Migration and Cutover 39b Wrapper Repository Packaging 40 Engineering Handbook 41 Repository Structure and Import Chain 42 Configuration Ownership Boundaries 43 Adding Packages and Flake Inputs 44 Adding a Module or Profile 45 Adding a Host 46 Adding or Migrating a Service 47 Testing and CI Contracts 48 Secrets Implementation Conventions 49 Documentation Maintenance 50 NixOS Learning Path 51 Guided Repository Tour 52 Nix Language Essentials 53 Declarative Configuration Store and Generations 54 Flakes and Inputs 55 NixOS Modules and Option Merging 56 SpecialArgs and Home Manager Argument Flow 57 Electra Specialisations Worked Example 58 Nix Troubleshooting Primer 90 Historical Material 91 Electra Secure Boot Hardening Record Home
1 24 ADR 004 Engram Durable Agent Memory
Nimmo edited this page 2026-09-12 16:58:12 +01:00
Table of contents

ADR-004: Use Engram for durable agent context, not canonical project truth

  • Status: Accepted
  • Date: 2026-07-03
  • Scope: Coding-agent memory, cross-session context, project scoping, and documentation boundaries
  • Supersedes: Mem0 and Graphiti agent-memory integrations
  • Superseded by: None

Context

Coding agents regularly rediscover facts that are expensive to reconstruct but too small or too contextual for a permanent manual: user preferences, architectural rationale, recurring operational constraints, confirmed failure causes, and concise outcomes. Conversation history alone does not reliably survive new sessions or context compaction.

The fleet first implemented a self-hosted Mem0 service, custom MCP adapter, PostgreSQL/pgvector storage, and remote model dependencies. It then replaced Mem0 with a central Graphiti/Neo4j service before replacing Graphiti with Engram the following day. The Engram change removed the central MCP dependency: each client launches a pinned local binary over stdio, writes local memory, and can replicate through the separately hosted Engram Cloud service.

The repository does not preserve a single contemporary comparison document for all three systems. The operational rationale is therefore partly inferred from the change sequence: Mem0 and Graphiti accumulated server, database, model, embedding, endpoint, adapter, and authentication integration, while commit 9c2761c deliberately replaced that stack with local MCP processes and optional autosync. The current memory policy and continued implementation confirm the boundary described below.

Decision

Use Engram as the durable cross-session context layer for repository-aware agents.

  • Codex and OpenCode launch the pinned engram binary locally using the MCP stdio transport. A working memory tool does not depend on the shared cloud service being online.
  • Local Engram storage remains authoritative for each client. Engram Cloud on Vega replicates project observations across clients; it is a synchronization layer, not the only copy and not the MCP execution path.
  • Repository identity is explicit. .engram/config.json pins this repository to project nixos-config; reads and writes must stay in that project scope unless the user deliberately requests cross-project work.
  • Agents retrieve relevant context near the start of substantive work and after compaction. They store only durable, confirmed facts that will save future reconstruction effort.
  • Before writing, agents search for an existing observation and update it when the fact has evolved rather than creating near-duplicates.
  • Memories must never contain secret values, authentication material, raw secret-bearing output, transient logs, speculative diagnoses, or routine command output.

Engram is explicitly non-canonical. Current repository configuration, wiki policy/reference/runbooks, Forgejo work records, and direct user instructions override memory. A retrieved observation is a discovery aid and must be verified before consequential action.

Unfinished work must not exist only in Engram. Active plans and acceptance evidence belong in Forgejo; implemented behavior belongs in source; reusable knowledge and accepted rationale belong in the wiki. Engram may preserve a confirmed finding until it warrants promotion, but promotion does not make the memory a competing source of truth.

Consequences

  • Agents can resume non-obvious work across sessions and context compactions without treating chat transcripts as a project database.
  • Local stdio operation reduces dependence on a central HTTP MCP service and permits memory access during a replication outage.
  • Cloud replication still introduces a hosted service, PostgreSQL state, credentials, network exposure, and backup obligations. These are operational concerns, not evidence that cloud state is canonical.
  • Explicit project scoping reduces accidental cross-repository contamination; every repository that uses the pattern needs a stable project identity.
  • Memory quality depends on restraint. Saving speculation, secrets, or facts already clear in version-controlled documentation makes retrieval less safe and useful.
  • Agents must spend time verifying recalled information. This is intentional: memory optimises discovery, not authority.
  • Important decisions cannot remain solely in observations. They must be promoted to an ADR or other owned documentation surface when they become a lasting constraint.
  • Exporting Engram observations for analysis does not change their status; an export is still derived context rather than canonical documentation.

Alternatives considered

Rely on conversation history only

Rejected. Sessions and context windows are temporary, and a transcript is neither searchable durable state nor a reliable handoff contract.

Store all agent context in repository files or the wiki

Rejected. It would commit transient working context and small observations into surfaces intended for executable behavior or curated durable knowledge. It would also make retrieval depend on knowing the right document in advance.

Continue with Mem0

Superseded after implementation. The repository history shows a custom adapter, central service, database/vector infrastructure, model-backed extraction, and several stabilization changes. That was more coupled operational machinery than the eventual local-memory path.

Continue with Graphiti

Superseded after a short trial. It simplified some client behavior relative to Mem0 but retained a shared MCP service, Neo4j, and remote extraction/embedding dependencies. Engram provided a smaller local MCP boundary with optional replication.

Treat synchronized agent memory as canonical documentation

Rejected. Memories may be stale, selectively captured, or written before full validation. Giving them authority would bypass review, provenance, page ownership, and the separation between work tracking and lasting knowledge.

References

  • Current ownership boundary: Documentation Map and Scope
  • Current control-plane implementation: Automation and Control Plane
  • Current source: .engram/config.json, AGENTS.md, modules/profiles/memory-policy.md, modules/common/engram-package.nix, modules/profiles/ai-agents.nix, and modules/services/engram-cloud.nix
  • Mem0 integration and stabilization: repository commits 3b0ec02e992ae52fe759d89720dc48df094e3224 and b09de01bf9eb4d8c5f948969c02c2ea2c047e6c5
  • Mem0 replaced by Graphiti: repository commit 37cbe4149d73db6b389ccdfb366a6503d782cfbb
  • Graphiti replaced by Engram: repository commit 9c2761c24ac612889cb6a75f212f8eb937070257
  • Engram session lifecycle policy: repository commit c7e0a6837de0162f9bf78ae50b424cae90a0962a
  • Superseded implementation work: Forgejo issues #44, #45, and #46