A cognitive memory proxy that gives LLMs persistent, project-aware context across sessions. It sits between a client (IDE, CLI, VS Code chat, or another agent like Hermes) and any upstream LLM, silently giving that LLM durable memory: it intercepts OpenAI-compatible chat requests, embeds the user's prompt, recalls relevant memories from a PostgreSQL + pgvector store, injects them into the system prompt, forwards the enriched request to the upstream model, streams the response back, and β in the background β extracts new durable facts from the conversation for future recall.
π§ Your AI assistant remembers everything β without bloating context windows.
- What Engram Is
- How It Works
- Memory Model: Genome & Phenotype
- Architecture
- Project Structure
- Quick Start (Docker)
- Client Configuration
- Configuration
- Local Development (No Docker)
- Web GUI
- API Overview
- Troubleshooting
Engram is a hand-rolled Node.js/TypeScript HTTP server β no Express/Fastify β that acts as an intelligent proxy between clients and an LLM. It is biologically inspired (genome/phenotype memory model, Ebbinghaus decay, a "hippocampus" consolidation cron) and built around ten capabilities:
- Memory recall & injection β every request is embedded, vector-searched against a PostgreSQL + pgvector store, and enriched with a
[ENGRAM COGNITIVE CONTEXT]block before being forwarded upstream. - Generative extraction β after each conversation, a configurable generative model extracts new durable facts from the transcript and stores them (with quality gates, dedup, and embedding).
- Compaction engine β long conversations are summarized in-place so context windows never grow unbounded.
- Consolidation cron ("the hippocampus") β a two-tier background job that merges, promotes, and prunes memories to keep the knowledge base healthy.
- Trace observability β every request/response is captured to a persistent
tracesstore (credentials redacted on capture) and auto-scored by a dedicated LLM judge (recall relevance / extraction fidelity / answer quality), with calibration, consistency checks, policy thresholds, and a review loop. - Integrity engine (auto-heal) β deterministic store checks + LLM-judged false-memory detection, with a gated Tier-2 that supersedes/deletes noise; everything lands in a findings ledger first.
- Enrichment engine (auto-optimization) β the memories you use most that are weakest get sourced enrichment from the store itself, the codebase (rg,
file:line), and the web β as reversible superseding successors, never in-place rewrites. - Audit trail + undo β every mutation (extraction, consolidation, integrity, enrichment, manual edits) writes a before/after audit row; supersedes, deletes, updates, and enrichments are one-click undoable from the GUI.
- Memory coherence (the "living skill") β extraction attaches a context frame (project/module/file/topic) to every fact and links related facts into graph clusters (
part_of/derives_from/related_toedges); on recall, a bundle composer assembles the cluster into a dense, ordered, source-anchored knowledge bundle β "when I say I'm working on Engram, Engram gives me the Engram skill, auto-maintained." - Repo baseline index β enter a repo URL or local path in the web GUI; Engram structurally maps the repo into the store (files/exports/imports/calls via T1 line-based + T2 tree-sitter miners, zero LLM), mines git history (commits, mutations, reverts β "remember what broke"), tags everything with the repo identity, redacts secrets, supersedes on re-index, and suggests indexing when you're continuously working in an unindexed location.
The whole system is organized as a four-rung trust ladder: calibration β integrity (validity) β optimization (enrichment) β coherence (context) β no engine mutates memories until the judge it depends on is calibrated, and every mutation is audited and reversible.
It can run in two deployment modes:
- Standalone smart proxy β clients point at
http://<host>:8098/v1/chat/completions; Engram embeds/recalls/weaves/forwards/streams and does all orchestration itself. - Hermes sidecar (Option B) β Engram is not the chat proxy. Hermes talks to its own LLM; Engram is a memory + cognition engine reached over HTTP:
prefetch()injects genome + recalled phenotype into each turn,sync_turn()ingests each completed turn. See Client Configuration.
Engram is fully model- and provider-agnostic: embeddings, generative extraction, and the upstream chat model are all resolved through the Settings-tab registry (Settings β env override β fail; see Configuration). In the live deployment a single LAN llama-swap box serves all three roles.
The heart of Engram is the chat-completions route in packages/engram-js/src/api/routes/chat/completions/route.ts. The full flow:
- Authenticate & validate β
x-api-key/ Bearer /ApiKeyheader (public endpoints are only/health,/api/performance/system,/api/performance/llama-swap). An authenticateduser_idoverrides any client-supplied one (impersonation guard). The session id resolves fromx-session-idheader β body β query β a deterministicsha256(user_id:project_id)(so all turns of one conversation group automatically). - Embed the query β the last user message is embedded via the per-facet provider chain: primary provider β fallback providers in order β deterministic synthetic hashing embedding (feature-hashed tokens + n-grams), so embedding never hard-fails.
- Recall memories β
- 𧬠Genome (core directives): fetched with a direct SQL query, cached in-memory for 30s (
genomeCache), always injected. - π¬ Phenotype (context): hybrid recall β pgvector cosine search fused with a
pg_trgmkeyword search, re-ranked by an evidence-fusion score (P = 1 β (1βp_vec)(1βp_lex)), scaled by importance and penalized for open contradictions. Top 5 results are mapped to{id, content, sector, score}.
- 𧬠Genome (core directives): fetched with a direct SQL query, cached in-memory for 30s (
- Auto-search (optional) β if enabled (
EG_AUTO_SEARCH_ENABLED) and the top recall score is below the confidence threshold (EG_AUTO_SEARCH_MIN_CONFIDENCE, 40%) for a tech-style prompt, Engram queries SearXNG via the searxNcrawl MCP server and weaves a--- WEB CONTEXT (auto-retrieved) ---block into the prompt. - Weave the context block β
buildCognitiveContext()produces the[ENGRAM COGNITIVE CONTEXT]block: genome bullets, phenotype grouped by sector, then web results β closed with an instruction to use the context silently. Prior history is sanitized (Engram status artifacts andreasoning_contentthinking tokens stripped) before injection. - Compact if needed β when the sanitized message count exceeds
EG_COMPACT_TRIGGER(code default 50,.env.example100), the compaction engine runs before forwarding (see below). - Forward upstream β the enriched payload goes to
EG_UPSTREAM_LLM_URL(/chat/completions) via a retrying fetch with a per-host circuit breaker; llama-swap requests are serialized per model through a promise-chain lock. All original fields (tools, temperature, β¦) pass through. - Stream back via SSE β tokens pipe transparently to the client; Engram's status arrives as valid OpenAI-format
chat.completion.chunkdeltas, so any OpenAI-compatible client renders it natively:π§ Injected 𧬠N genome, π§ M memories, π¦ K facts, π S sources, then a final_tracepayload (the "Engram Memory Trace" shown by the VS Code extension) anddata: [DONE]. - Extract in the background β
logInteractionAsync()is fire-and-forget: it never blocks the stream.
After each turn, the generative model (EG_MODEL_GENERATIVE via EG_GENERATIVE_URL) analyzes the conversation:
- Cooldown gate β skips if an extraction ran within
EG_EXTRACTION_COOLDOWN_MS(30s) or the response is under 50 chars. - Prompt hygiene β the full extraction directive (including the entire DO-NOT-EXTRACT list: IDE-save diffs, session state, build results, secrets, vague boilerplate) goes in the system role; only truncated user prompt (2500 chars) + response (3000 chars) go in the user role.
- Quality gate β
isWorthRemembering()enforces a hard floor (15β400 chars) and regex-rejects leaked secrets, ephemeral session state, boilerplate, and self-referential memory meta β the last line of defense that keeps the store clean. - Dedup β exact-content check plus a normalized substring near-duplicate check against active rows.
- Storage β every write funnels through the single transaction chokepoint
rememberDurableMemory()(src/durable/repository.ts), which classifies genome vs phenotype, infers a sector, scores importance, applies bitemporal timestamps, embeds the content, writes version 1 + provenance + audit log, and (for long memories) windowed embeddings.
When a conversation exceeds EG_COMPACT_TRIGGER messages, the compaction engine keeps context bounded (invoked in the request path, before forwarding):
- Isolate β split into old history + a recent raw tail (
EG_MAX_RAW_TURNS, code default 6,.env.example4); tool-call boundaries are fixed so no orphan tool results break the upstream API; the last user message is preserved for continuity. - Thin β truncate oversized tool outputs (>800 chars), assistant responses (>1200), and user messages (>1000); drop consecutive duplicate tool calls.
- Summarize & extract in one LLM call β the compacted history goes to the generative model, which returns JSON
{summary, facts[]}(temperature 0.1, capped atEG_COMPACT_PROMPT_MAX_CHARS). - Save facts β extracted facts are stored via
rememberDurableMemorywithsource: "compaction_engine"(one failed save rolls back the batch). - Reconstruct β old history is replaced with
[COMPACTED SESSION SUMMARY]plus the raw tail. If the LLM call fails, old history is dropped silently and only the raw tail survives β context never grows. A cooldown (EG_COMPACTION_COOLDOWN_MS, default 10s) prevents hot-looping.
A background cron (started 2s after boot) with two env-overridable tiers:
| Tier | Interval | Window | Min group | Purpose |
|---|---|---|---|---|
| RECENT | EG_CONSOLIDATION_RECENT_INTERVAL_MS (4h) |
last β¦_RECENT_MAX_AGE_DAYS (7d) |
2 | Promote standing rules / catch near-dupes within hours |
| DEEP | EG_CONSOLIDATION_DEEP_INTERVAL_MS (24h) |
up to β¦_DEEP_MAX_AGE_DAYS (30d) |
3 | Long-window cleanup (requires access_count >= 1) |
Each cycle groups non-archived memories by consolidation_hash (max 15 groups), sends each group (chunked to β€150 memories per call) to the generative model, and applies the returned merge | update | promote | delete actions in one transaction β any error rolls back the whole batch. If the LLM omits new_content for a merge/update, the consolidation model synthesizes it. Manual trigger: POST /api/dashboard/consolidate (?tier=recent / ?tier=deep / default = both tiers).
Every request that flows through Engram is captured to a persistent traces table β route, status, latency, direction (in/out), model, genome/phenotype injection breakdown, and the full request/response bodies (credential-like patterns regex-redacted on capture; body capture capped by EG_TRACE_MAX_BODY_CHARS). Traces are kept for EG_TRACE_RETENTION_DAYS (pruned automatically) and browsed in the GUI Traces tab:
- Auto-scoring β eligible traces (chat/ingest/recall,
status < 400) are scored by a dedicated, fully independent judge model (Settings β Judge; observed live:Qwen3.6-28B-REAP20on the llama-swap box), one dimension per trace type: chat βanswer_quality, ingest βextraction_fidelity, recall βrecall_relevance. Rate:EG_TRACE_AUTO_SCORE_RATE(default 1 = every eligible trace). - Score pills + needs-review flags β low-scored traces (< policy
badthreshold) are flaggedneeds reviewuntil opened (or marked reviewed); the review loop is the human-in-the-loop for judge output. - Report β
POST /api/dashboard/traces/reportaggregates the window (distribution by route/direction/label, score stats per dimension, worst traces) and generates deterministic remediation suggestions from live model resolution (never hardcoded historical defaults), plus policy alerts when a dimension's average falls below the good/bad thresholds. - PDF export β the report renders to pixel-perfect PDF via vendored
html2canvas-pro+jsPDF(local-first, no CDN at runtime).
The "trust the judge" checkpoint β no score-driven mutation happens until the judge itself is calibrated and stable:
- Calibration set β curated traces with human-labeled expected scores (
judge_calibrationtable; the GUI lets you add any trace with your expected score).POST /api/dashboard/judge/run-calibrationre-scores each entry and reports agreement rate + mean absolute error. Observed: 83% agreement, avg abs error 0.067 on the first seed set. - Consistency check β
POST /api/dashboard/judge/consistencyre-scores a random sample NΓ (non-persisting) and reports per-trace mean/MAD. Observed: MAD = 0 (deterministic judge). - Policy thresholds β good/bad score thresholds (
EG_POLICY_GOOD_THRESHOLD/EG_POLICY_BAD_THRESHOLD, defaults 0.7/0.4) drive ScorePill colors, the needs-review flag, report distributions, and the suggestions engine β all resolved live, never hardcoded. - Automatic gate β a judge-calibration gate (min calibration agreement + max MAD,
EG_INTEGRITY_MIN_CALIBRATION/EG_INTEGRITY_MAX_MAD) opens/closes Tier-2 mutation authority; a closed gate shows a flashing red banner in the GUI.
A background scheduler (default 24h, EG_INTEGRITY_INTERVAL_MS) that runs 9 deterministic checks (duplicate content, empty content, missing embeddings, synthetic embeddings, null sectors, archive-eligible, near-dupes, secret leakage, broken links) plus an LLM-judged false-memory sampler:
- Tier 1 (deterministic) β acts immediately, audited (
actor: auto-heal): deletes empty-content memories, supersedes near-identical duplicates (>0.92 sim), re-embeds nulls when the embed box is up. - Tier 2 (LLM-judged) β samples the oldest never-accessed memories (skipping any with an open finding), asks the judge if each is a real fact, and acts per
EG_INTEGRITY_TIER2_ACTION:flag(default β findings only),supersede, ordelete(both gated on judge calibration + a confidence floor,EG_INTEGRITY_DELETE_CONFIDENCE). - Findings ledger β every Tier-2 result lands in
integrity_findings(open β resolved/dismissed) with the verdict (delete/supersede candidate), the judge's score and reason, and the memory content; the GUI's Memory Audit tab shows what would happen before you click. - Apply / Dismiss β Apply performs the deferred repair through the shared audited mutation layer (delete = hard delete with before-state; supersede = reversible); Dismiss closes the finding untouched. Access-grant findings for out-of-allowlist enrichment directories work the same way (Apply = grant).
The third rung: it takes the memories the user actually uses that are weakest and improves them with sourced evidence, never rewriting in place:
- Selection β pool = semantic/procedural, active, embedded, never genome (column OR
metadata.is_genome) and never intent/TODO/preference content (deterministicisIntentOrTodogate β "user wants toβ¦", "needs updating", "shouldβ¦", "remindβ¦"), ordered by usage; a completeness-rubric judge call scores the batch (0 = complete, 1 = critically incomplete). - Sources, in order β (a) the store itself (related memories β₯ 0.85 sim), (b) codebase β
rgover the allowlisted roots (EG_ENRICHMENT_SEARCH_ROOTS, default~/Apps; directories outside it surface grant/deny access-request findings β Apply persists the root), (c) web β searxNcrawl (default on), technical facts only. A grounding judge gate drops any source about a different project/tool before compose. - Compose + validate β a compose rubric keeps the original verbatim and appends sourced additions tagged
[src:N]; a validate rubric rejects cross-project drift, unsupported additions, and hallucination (score β₯ 0.6 required). - Mutate β
enrichMemory()creates a successor (fresh uuid, fresh embedding,metadata.enriched_from) and supersedes the original: one audit row, one undo click. Action:EG_ENRICHMENT_ACTIONβflag(default since the 2026-08-07 contamination incident; a clean reviewed batch earnsapplyback) orapply.
Every mutation to the memories table β extraction, consolidation actions, integrity repairs, enrichment, manual GUI edits β writes an audit_log row with before_state and after_state (embedding included, so even a hard delete is faithfully restorable). The Memory Audit tab renders the trail; undo (one click per row) reverses:
| Operation | Undo does |
|---|---|
supersede |
clears superseded_at β memory active again |
delete |
re-inserts the full row including its embedding |
update / reclassify |
restores the captured before-fields |
enrich |
removes the enriched successor, restores the original (finding gets a red REVERTED badge) |
Undos write their own memory_undo audit row and are never themselves undoable. Reverted enrichments are stamped reverted_at on their finding so the ledger never claims a reverted enrichment still stands.
The rung that fixes the "Important decision: restructure conditional renderingβ¦" class β memories that are context-free because extraction dropped the specifics. Two halves:
- Extraction (root cause) β the extraction output schema is now
{context, facts[], links[]}:- Context frame β every fact from a turn carries
metadata.context = {project, module, file, topic}, so no fact is ever a floating fragment. - Specifics or nothing (hard rule) β a fact that would be meaningless without the conversation is rejected; a decision must include the concrete what/where/why. Measured via the existing
extraction_fidelityjudge dimension. - Links β extraction emits
links: [{from, to, type}](part_of/derives_from/related_toonly); the write path materializes them asedgesrows. Unsupported link types βcluster_link_evaluationfindings for judge/user (a memory is never dropped because it couldn't be linked β new projects start unlinked clusters, which is fine).
- Context frame β every fact from a turn carries
- Recall (the bundle) β
POST /api/memories/bundle?topic=X(and auto-detection in/api/cognitive-contextfor "working on X" phrases):clusterEnginefinds the anchor (top vector recall) β BFS over coherence edges (depth 2) β similarity neighbors (β₯ 0.75), then composes a dense, ordered bundle (architecture β current state β conventions β pitfalls) with every statement tagged[src:N], validated against hallucination/cross-project drift (β₯ 0.6). Read-only: bundles never write to the store, cache β€ 5 min per topic, and the memories stay the authority. The integrity engine gained check #9broken_links(edges whose endpoint memory is superseded β the graph can't rot silently).
The fix for the "forgetful on large projects" class β the store improves in real time from conversation turns, but never had the baseline knowledge of the repo itself (the plugin can't see the tool calls where the agent reads files). Enter a repo URL (shallow-cloned into the repos root) or a local path in the GUI β Repos tab, and Engram structurally maps the repo into the store:
- Structural mining, zero LLM β one memory per file:
{path, exports, imports, calls}. Two tiers: T1 line-based heuristics (zero deps) and T2 tree-sitter AST parsing (web-tree-sitter + vendored per-language grammars β verified syntax, call graph). T2 falls back to T1 on any parse failure; the index never fails. - Git history β if the location is a git repo: commits, per-file mutations, and revert detection β bi-temporal "remember what broke" memories ("Revert 'fix: adjust unit label' was reverted in commit 2c6b899 β do NOT re-introduce this change"), so recall surfaces past failures before the next edit.
- Discipline preserved β every memory carries
metadata.repo(the canonical identity:owner/repofor URLs, the path for local β a same-named repo from a different owner can never mingle), secrets are redacted, re-index supersedes per-file (audited, undoable), runs are locked and progress-reported, and delete supersedes everything with one click. - Working-location tip β after 3 cognitive-context injections in a session whose project has no indexed repo, one honest note is appended: "this repo isn't indexed β add baseline knowledge (Web GUI β Repos)." Once per session, toggleable, never automatic.
- Auto-refresh β a scheduled pass rescans every ready repo (newest-file-mtime + root-dir mtime + git HEAD fingerprint) and re-indexes anything that changed β "I keep working in the repo" stays in sync without clicking Reindex. Interval
EG_REPO_REFRESH_INTERVAL_MS(default 30 min), toggleEG_REPO_AUTO_REFRESH, manualPOST /api/dashboard/repos/refresh.
Temporal salience with access-based reinforcement and exponential decay:
- Base decay rate: 1% per day (
DEFAULT_DECAY_CONFIG.baseRate, configurable) - Genome multiplier: genome memories decay at 30% the phenotype rate (
genomeMultiplier: 0.3) - Access reinforcement: each access reduces effective age by 7 days (
accessReinforcementDays: 7) - Per-sector rates at extraction: episodic 0.15, semantic/procedural 0.05, genome 0.03, default phenotype 0.1
- Salience decays exponentially and feeds
memory_tiertransitions (active/warm/cold/archived). The decay job runs viaPOST /admin/decay/run.
| Layer | Behavior | Description |
|---|---|---|
| 𧬠Genome | Immutable, near-never-decaying | Core directives β foundational facts always injected into every request (e.g. "User prefers TypeScript"). Stored as is_genome = true, cached 30s, retrieved by direct SQL (not similarity). |
| π¬ Phenotype | Decaying context via vector search | Context retrieved by similarity across 5 sectors, with per-sector decay rates. |
Genome classification is deliberately opt-in: classifyAsGenome() matches explicit GENOME_PATTERNS (capitals/definitions/scientific constants/mathematical identities/precisely-anchored historical dates) or an explicit is_genome flag at write time. The old heuristic that promoted any short declarative sentence to genome was removed β it flooded the genome tier with ephemeral facts.
Sector is inferred from content keywords, then coerced through normalizeSector β a closed 5-value enum enforced at the DB boundary, so an LLM can never persist an invented sector like "important decision".
| Sector | Type | Example |
|---|---|---|
π semantic |
Facts & domain knowledge | "PostgreSQL uses pgvector for embeddings" |
βοΈ procedural |
Code patterns & workflows | "Auth middleware validates JWT tokens before route handlers" |
π¬ episodic |
Events & specific interactions | "User debugged the Docker compose setup on March 15" |
π emotional |
Preferences, tone, sentiment | "User prefers concise, no-nonsense explanations" |
π reflective |
Meta-cognition & lessons learned | "When debugging Docker networking, always check subnet conflicts first" |
π Editable source:
docs/assets/architecture.excalidrawβ drag it onto excalidraw.com (or open with the Excalidraw VS Code extension) to edit. The Mermaid source below is kept for reference.
flowchart TD
classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef engram fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef db fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef up fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
classDef bg fill:#f0f0f0,stroke:#666,stroke-width:1px
U["π€ Client β IDE / CLI / VS Code / Hermes sidecar"]:::user
subgraph ENGRAM["π₯οΈ Engram server (:8098) β packages/engram-js"]
E1["POST /v1/chat/completions<br/>auth Β· session Β· sanitize"]:::engram
E2["Embed query (provider chain β synthetic)"]:::engram
E3["Recall: 𧬠genome (cache 30s) + π¬ phenotype<br/>hybrid vector + keyword fusion"]:::engram
E4["Auto-search (optional)<br/>searxNcrawl MCP :9555"]:::engram
E5["Weave [ENGRAM COGNITIVE CONTEXT]<br/>into system message"]:::engram
E6["Compaction if > EG_COMPACT_TRIGGER"]:::engram
E7["SSE stream back + π§ status + _trace"]:::engram
E8["Async extraction (gates Β· dedup Β· embed)<br/>memoryLogger.ts"]:::engram
E9["rememberDurableMemory β write chokepoint"]:::engram
end
subgraph DB["ποΈ PostgreSQL + pgvector (engram db)"]
T1["memories Β· memory_windows Β· memory_versions"]:::db
T2["provenance Β· entities Β· edges Β· contradictions"]:::db
T3["audit_log Β· traces Β· judge_calibration Β· judge_evals"]:::db
T4["integrity_runs Β· integrity_findings Β· app_settings"]:::db
end
subgraph UP["π Upstream LLM box (llama-swap / OpenAI)"]
U1["/v1/chat/completions"]:::up
U2["/v1/embeddings"]:::up
U3["generative model (extract/compact/consolidate)"]:::up
end
subgraph BG["βοΈ Background engines (trust ladder)"]
B1["Consolidation cron (RECENT 4h / DEEP 24h)"]:::bg
B2["Trace capture + judge auto-score"]:::bg
B3["Integrity engine (auto-heal, gated Tier-2)"]:::bg
B4["Enrichment engine (sourced successors)"]:::bg
B5["Decay job Β· activity ring buffer"]:::bg
end
U -->|"POST /v1/chat/completions"| E1
E1 --> E2 --> U2
E2 --> E3 --> T1
E3 --> E4 --> E5
E1 --> E6 --> E5
E5 --> U1
U1 -->|"SSE tokens"| E7 -->|"stream + status + trace"| U
E7 --> E8 --> U3
E8 --> E9 --> T1
E9 --> T2
E9 --> T3
B1 --> T3
B2 --> T3
B3 --> T3
B3 --> T4
B4 --> T3
B4 --> T4
B5 --> T1
B5 -.->|"web GUI :8099"| U
The repo is an npm-workspaces monorepo (root package.json workspaces: packages/engram-js + apps/web; root scripts dev/build/start/test mirrored by the Makefile):
Engram/
βββ packages/
β βββ engram-js/ # The Engram server (TypeScript, tsc β dist/, runs `npm start`)
β βββ src/
β βββ api/ # Hand-rolled HTTP app + middleware + routes
β β βββ routes/ # chat/completions (the proxy), recall, memories/*, ingest/*,
β β # dashboard/*, ide/*, consolidations, contradictions, admin, stats, sources
β βββ durable/ # schema.ts (31 tables, idempotent SQL), repository.ts (write/read
β β # chokepoints), mutations.ts (shared audited mutations + undo), scoring.ts
β βββ embeddings/ # embed.ts (6 providers + synthetic fallback + normalizeEmbedding), facets.ts
β βββ services/ # memoryInjector, memoryLogger, compactionEngine, consolidationEngine,
β β # traceStore, traceScorer, traceGovernance, integrityEngine,
β β # enrichmentEngine, hybridSearch, autoSearch, windowedEmbedder, ...
β βββ database/ # connection (pg pool), migrate.ts (idempotent boot migrations), models.ts
β βββ configuration/ # env loading + parsing (envFile.ts, index.ts)
β βββ mcp/ # MCP server/client surface (engram_store, engram_search, ...)
βββ apps/
β βββ web/ # Web GUI β React 18 + Vite + Tailwind SPA (host port 8099, nginx proxy
β β # target; proxies /api/ β engram:8080 with SSE-friendly buffering off)
β βββ vscode-extension/ # "Engram for VS Code" β separate repo (engram-vscode, publisher
β β # Nullure); @cortex chat participant, auto-links cursor/claude/windsurf
β β # configs, IDE session tracking, Memory Trace rendering
β βββ searxNcrawl/ # Auto-search service (git submodule) β Python FastMCP server on :9555
β β # exposing crawl / crawl_site / search; SearXNG sidecar config
β βββ hermes-plugin/ # Hermes memory-provider plugin ("Option B" sidecar; stdlib urllib only)
βββ docs/ # model-config-audit.md (config reference), model-breakdowns.md,
β β # trace-observability-plan.md, governance-plan.md,
β β # memory-integrity-plan.md, optimization-plan.md, todo.md, archive/
βββ scripts/ # recall-eval (recall@k harness), backfill_embeddings.py,
β β # backfillEmbeddingProvenance.ts, store-hygiene purge scripts (DRY-RUN by default)
βββ docker/ # postgres init scripts (databases, vector/halfvec extensions)
βββ docker-compose.yml # postgres Β· redis Β· engram Β· searxng Β· searxncrawl Β· web
βββ bin/opm.js # `engram` CLI (watch β /api/dashboard/activity, memory CRUD)
Notable subsystems: src/sources/* (GitHub/Drive/Notion/OneDrive/crawler connectors), src/ingestion/* (document chunking/extraction), src/vectorStores/* (adapters for qdrant/pinecone/weaviate/chroma/milvus/valkey β the default deployment stays on Postgres), src/durable/localstore.ts (SQLite fallback via EG_STORAGE=sqlite).
# Build and start everything
docker compose up --build -d
# Check status
docker compose ps
# View logs
docker compose logs -f engram| Service | Host port | Description |
|---|---|---|
| postgres | 5432 | PostgreSQL 16 + pgvector (pgvector/pgvector:0.8.2-pg16-trixie) β memory storage |
| redis | 6379 | Redis 7 cache |
| engram | 8098 β 8080 | The Engram server β main API endpoint (healthcheck on /health) |
| searxng | 8888 | SearXNG metasearch (for auto-search; cap_drop: ALL) |
| searxncrawl | 9555 | Auto-search FastMCP server (crawl/search tools) |
| web | 8099 | Engram Web GUI β nginx serving the React SPA, proxying /api/ β engram:8080 |
All services share the ftr10-engram bridge network; named volumes postgres_data, redis_data, server_data persist data. There is no bundled Ollama service β Engram expects models to be reachable via env-configured URLs (in the live deployment a LAN llama-swap box serves embeddings, the generative model, and the upstream chat model; see Configuration).
Observability: Langfuse was wired in, then removed as dead weight (its SDK remains a dormant dependency, gated by
EG_LANGFUSE_ENABLED, default off). It was replaced by the in-house trace store + LLM judge (Traces tab, Governance tab) and the Memory Audit tab (integrity findings + audit trail + undo) β the Web GUI (port 8099) is the primary dashboard: live server logs, memory activity, recall, performance metrics, traces with scores, governance, and the audit trail.
# Stop all services
docker compose down
# Stop and remove all data volumes (fresh start)
docker compose down -vPoint your IDE or CLI tool at the Engram proxy (OpenAI-compatible):
http://<your-server-ip>:8098/v1
The proxy forwards enriched requests to the upstream LLM configured via EG_UPSTREAM_LLM_URL. Engram's SSE status messages are valid OpenAI-format deltas, so any OpenAI-compatible client (Cline, custom CLI, SDK) renders them natively.
The extension activates on startup, connects to http://localhost:8098 (configurable engram.backend_url), and:
- Auto-links cursor/claude/windsurf/copilot/codex client configs to point at the Engram proxy
- Runs an ActivityObserver polling
/api/dashboard/activityfor live traffic in the status bar / Dashboard panel - Tracks IDE sessions (
/api/ide/session/start|end,/api/ide/events) and exposesengram.queryContext/engram.addToMemory - Registers the
@cortexchat participant, which forwards prompts through Engram and renders the collapsible "π§ Engram Memory Trace" from the_traceSSE payload
When wired into Hermes Agent as a native memory-provider plugin, Engram is not the chat proxy β Hermes talks to its own LLM and Engram is a sidecar memory + cognition engine:
- Before each turn β
prefetch()callsPOST /api/cognitive-contextβ Engram composes the whole block server-side (cached genome + hybrid phenotype recall, plus gated outward web search only when inward recall is weak) and returns it as a single string injected into the turn as a<memory-context>block. Falls back to local genome +POST /recallon Engram builds without the route. - After each turn β
sync_turn()hands the turn (user message + assistant reply) toPOST /ingest/conversationso Engram's extraction LLM decides what to store (genome promotion is explicitly disabled for chat turns β genome is reserved for explicitengram_remember(genome: true)). Tool calls/results are deliberately not forwarded β raw tool output is noise without a heavy filter (see the IDE-save diff lesson). - Engram's chat proxy, compaction, and auto-search are not used in this mode; consolidation / decay / contradiction are exposed as
engram_consolidate/engram_decay/engram_contradictiontools. - The plugin lives at
apps/hermes-plugin/(copied to~/.hermes/plugins/engram/); activate withhermes config set memory.provider engram. No MCP server β stdliburllibonly.
The web GUI Settings tab is the single source of truth for providers, models, and tuning
(see Web GUI). It is persisted in Postgres (app_settings table, schema
4.4.0-integrity) and applied at boot β settings win over .env. The API is
GET/PUT /api/settings plus POST /api/settings/test (saves all settings, then live-tests a
section against the provider). There are no hardcoded model-name defaults anywhere in the
codebase. Settings are organized into thirteen groups (Provider, Generative, Embedding,
Judge, Server, Rate Limit, Compaction, Consolidation, Auto-Search, Traces, Policy, Integrity,
Enrichment) β see Web GUI.
.env (copy .env.example) now holds ONLY the values that cannot be GUI-managed β read at
startup before the settings store is available, or consumed by compose:
| Variable | Purpose |
|---|---|
EG_GENERATIVE_URL / EG_UPSTREAM_LLM_URL / EG_OPENAI_BASE_URL |
LLM-box base URLs (http://10.10.10.41:8080/v1 in the live deployment) |
EG_OPENAI_API_KEY |
Provider auth key |
EG_PG_HOST / EG_PG_PORT / EG_PG_DB / EG_PG_USER / EG_PG_PASSWORD / EG_PG_SCHEMA / EG_PG_SSL |
Postgres connection (startup) |
EG_REDIS_URL |
Redis connection (startup) |
EG_LOG_DIR / EG_LOG_MAX_LINES / LOG_LEVEL |
Logging (logger reads at static import) |
EG_INTERNAL_API_KEY / NODE_ENV |
Internal auth / runtime mode |
Engram loads .env from the cwd and up to four ancestor directories without overriding
already-set process env. A docker compose restart won't re-read a changed .env β use
docker compose up -d. (Compose no longer substitutes the LLM-box URLs from shell vars; the
.env values are authoritative.)
Legacy env overrides are still honored as a low-priority fallback for models
(EG_MODEL_GENERATIVE, EG_MODEL_EMBEDDING, EG_MODEL_EMBED_<FACET>, EG_CONSOLIDATION_MODEL)
and for general tuning knobs (EG_COMPACT_*, EG_CONSOLIDATION_*, EG_AUTO_SEARCH_*,
EG_RATE_LIMIT_*, β¦) β but they are no longer required.
All models resolve through src/database/modelRegistry.ts, in one order:
- Settings tab (Postgres
app_settings) β per-task / per-facet / master values - Env override (legacy vars above)
- Fail with a clear message (never a silent hardcoded model name)
- Generative β
resolveGenerativeModel(task)forextraction,compaction,consolidation, ordefault(master). A per-task setting beats the master model. - Judge β a fully independent model/provider (
resolveJudgeModel), deliberately separate from the generative chain:EG_JUDGE_MODEL/EG_JUDGE_URL/EG_JUDGE_API_KEYfallbacks. Used for trace scoring, false-memory sampling, and the enrichment completeness/grounding/compose/validate rubrics. - Embedding β
resolveEmbeddingModel(facet)forepisodic/semantic/procedural/emotional/reflective; per-facet beats the master embedding model. - Provider URL β
resolveProviderUrl(section); a per-section provider override beats the global provider (Settings β Provider: type OpenAI Compatible, host IP, port βhttp://host:port/v1).EG_EMBEDDINGS(provider kind) is derived from the provider type. - Embedding failure β if every provider fails, a deterministic synthetic hashing
embedding (feature-hashed tokens + n-grams, L2-normalized to
EG_VEC_DIM) is used, so writes never hard-fail on embedding (flaggedembedding_synthetic). Provider responses are normalized (normalizeEmbeddingβ some servers return numeric strings) and bound as JSON strings, the pgvector-safe convention.
Live deployment: one llama-swap box on the LAN (10.10.10.41:8080) serves embeddings,
generative extraction, and the upstream chat model. Configured models: Gemma-4-12B-no-thinking
(generative β extraction/compaction/consolidation), nomic-embed-text-v1.5 (embedding,
768-dim, all facets), and the judge runs on a second, fully independent model
(Qwen3.6-28B-REAP20) on the same box. Env fallbacks for the trust-ladder systems:
EG_TRACE_RETENTION_DAYS / EG_TRACE_MAX_BODY_CHARS / EG_TRACE_AUTO_SCORE_RATE,
EG_POLICY_GOOD_THRESHOLD / EG_POLICY_BAD_THRESHOLD, EG_INTEGRITY_* (enabled, interval,
sample size, min calibration, max MAD, delete confidence, tier-2 action, gate max age),
EG_ENRICHMENT_* (enabled, action, interval, pool/batch size, min incomplete, min usage,
search roots, web enabled, max web results).
# 1. Start PostgreSQL locally and create the database
sudo systemctl start postgresql
psql -U postgres -c "CREATE DATABASE engram;"
# 2. Install dependencies (npm workspaces)
npm install
# 3. Copy the minimal .env (only startup values: URLs, PG, Redis, log path)
cp .env.example .env
# edit .env: EG_PG_PASSWORD, EG_GENERATIVE_URL, EG_UPSTREAM_LLM_URL
# then configure models/providers in the web GUI Settings tab
# 4. Start the server (migrations run automatically at boot)
cd packages/engram-js && EG_PORT=8080 HOST=0.0.0.0 npx tsx src/server.ts
# 5. Or run the compiled build
npm run build && npm startMigrations are idempotent β the same IF NOT EXISTS statement list (src/durable/schema.ts, version 4.4.0-integrity, 31 tables incl. traces, judge_calibration, integrity_runs, integrity_findings, judge_evals) executes in one transaction at every boot, so the schema is always current before the API accepts traffic.
The web interface (React/Vite SPA on port 8099) is the primary dashboard:
- Dashboard β memory counts, genome/phenotype breakdown, sector/tier statistics, manual consolidation trigger
- Memory Explorer β search, filter by sector, edit, and delete stored memories; each row shows sector, genome/phenotype type, and an importance tier pill + score (critical/high/medium/low from the v4.0.0 schema)
- Server Logs β live auto-refreshing Pino logs
- Performance Monitor β CPU, memory, disk, and llama-swap metrics
- Memory Recall β test the real recall engine (
POST /api/dashboard/recall) - Activity β live memory read/write traffic (
/api/dashboard/activity) - Mindmap β visual knowledge-graph view of memories (clusters appear automatically once coherence edges exist)
- Traces β persistent request history with full bodies (secrets redacted), genome/phenotype breakdown, LLM-judge score pills, needs-review flags, filters, Generate Report (aggregates + deterministic remediation suggestions + policy alerts, PDF export), and per-trace score/delete/add-to-calibration actions
- Governance β judge calibration set (add any trace with your expected score, run calibration β agreement %, edit/delete), consistency check (N traces Γ R repeats β variance), and the needs-review queue
- Memory Audit β integrity findings ledger ("Would do" verdicts, Apply/Dismiss), the full audit trail (every mutation with before/after JSON), undo buttons, and Run integrity check / Run enrichment now triggers
- Settings β the single source of truth: Provider, Generative (master + per-task), Embedding (master + per-facet), Judge (independent model/provider), and General groups (Server, Rate Limit, Compaction, Consolidation, Auto-Search, Traces, Policy, Integrity, Enrichment), plus a read-only Advanced table (
.envvalues); Test & Save buttons live-validate each model section
# Dev mode (Vite + React, proxies /api β http://localhost:8080)
cd apps/web && npm run dev
# Production build
cd apps/web && npm run buildThe server exposes two families: root-level API routes (used by clients and the Hermes plugin) and dashboard routes (used by the Web GUI; nginx only forwards /api/ to the container, which is why recall is duplicated under /api/dashboard/recall).
| Endpoint | Method | Description |
|---|---|---|
/v1/chat/completions |
POST | OpenAI-compatible chat endpoint with memory injection (the proxy) |
/health |
GET | Health check |
/recall |
POST | Memory recall/search (embed query β hybrid recall) |
/api/cognitive-context |
POST | Shaped context block for the Hermes sidecar (genome + phenotype + gated outward web) |
/memories |
GET/POST | List / create memories |
/memories/:id |
GET / PATCH / DELETE | Read / update / delete a memory |
/memories/:id/explain |
GET | Explain why a memory was recalled |
/memories/:id/reinforce |
POST | Reinforce a memory (boosts salience) |
/memories/:id/tier |
POST | Change memory tier (active/warm/cold/archived) |
/memories/bundle |
POST | Coherence bundle for a topic β composed, source-anchored, read-only (?topic=X) |
/contradictions |
POST | Create a contradiction between memories |
/contradictions/:id/resolve |
POST | Resolve a contradiction |
/consolidations / /consolidations/claim / /consolidations/:id/complete |
POST | Consolidation lifecycle endpoints |
/edges/execute |
POST | Execute knowledge-graph edge operations |
/graph/temporal/query |
POST | Temporal graph query for memory relationships |
/ingest/conversation |
POST | Ingest a full conversation turn (Hermes sidecar) |
/ingest/document / /ingest/event / /ingest |
POST | Document / event ingestion |
/ingest/candidates/:id/accept / /reject |
POST | Promote / reject extraction candidates |
/sources/:source/ingest |
POST | Ingest from external sources (github, notion, googleDrive, onedrive, β¦) |
/admin/decay/run |
POST | Run the memory decay engine manually |
/stats/summary / /stats/timeseries |
GET | Memory statistics |
/api/dashboard/stats |
GET | Dashboard statistics (genome/phenotype breakdown) |
/api/dashboard/memories |
GET | List memories (paginated, searchable, sector filter) |
/api/dashboard/memories/:id |
PUT/DELETE | Update / delete a memory |
/api/dashboard/logs / /api/dashboard/log |
GET | Interaction logs / full Pino log file |
/api/dashboard/recall |
POST | Recall engine (browser-reachable duplicate of /recall) |
/api/dashboard/consolidate |
POST | Trigger consolidation (?tier=recent / ?tier=deep / both) |
/api/dashboard/perf |
GET | Server performance metrics |
/api/dashboard/activity |
GET | Live memory activity feed (ring buffer) |
/api/dashboard/traces |
GET | Persistent trace store β list (filters: route/direction/kind/status/scored/review) |
/api/dashboard/traces/facets |
GET | Route/status facets + live policy thresholds (good/bad) |
/api/dashboard/traces/:id |
GET / DELETE | Full trace incl. bodies / hard-delete one trace |
/api/dashboard/traces/:id/score |
POST | LLM-as-judge scoring (dimension=recall_relevance|extraction_fidelity|answer_quality) |
/api/dashboard/traces/:id/review |
POST | Mark a needs-review trace as reviewed |
/api/dashboard/traces/report |
POST | Window aggregation + score stats + deterministic suggestions + policy alerts |
/api/dashboard/traces / /api/dashboard/traces/prune |
DELETE | Clear all traces / hard-delete older than retention (?days=N) |
/api/dashboard/judge/calibration |
GET/POST | Judge calibration set (human-labeled expected scores) |
/api/dashboard/judge/calibration/:id |
PUT/DELETE | Edit / remove a calibration entry |
/api/dashboard/judge/run-calibration |
POST | Re-score every calibration entry β agreement rate + mean abs error |
/api/dashboard/judge/consistency |
POST | Re-score N traces Γ R repeats (non-persisting) β per-trace mean/MAD |
/api/dashboard/integrity/run |
POST | Run the integrity engine now (8 checks + judged false-memory sample) |
/api/dashboard/integrity/status |
GET | Engine enabled/action/last run + gate state |
/api/dashboard/integrity/findings |
GET | Findings ledger (verdicts, memory content, successor_live) |
/api/dashboard/integrity/findings/:id/resolve |
POST | Apply (performs the deferred repair / grants access) or Dismiss |
/api/dashboard/memory-audit |
GET | Audit trail (every mutation with before/after state) |
/api/dashboard/memory-audit/:id/undo |
POST | Undo a supersede/delete/update/reclassify/enrich (one-click reversibility) |
/api/dashboard/enrichment/run |
POST | Run the enrichment engine now (used-most Γ completeness β sourced successors) |
/api/dashboard/enrichment/status |
GET | Enrichment enabled/action/last run |
/api/dashboard/coherence/link-backfill |
POST | One-time legacy link backfill β SQL-only, idempotent related_to edges (sim β₯ 0.85, capped) |
/api/dashboard/candidates/process |
POST | Drain extraction candidates through the real extraction pipeline (?limit=N) |
/api/dashboard/activity/clear |
POST | Clear the activity feed |
/api/performance/system |
GET | System metrics (CPU, memory, disk, load, uptime) |
/api/performance/llama-swap |
GET | Upstream llama-swap box metrics |
/api/ide/session/start Β· /api/ide/session/end Β· /api/ide/events Β· /api/ide/context Β· /api/ide/patterns/:session_id |
GET/POST | VS Code extension integration endpoints |
Common issues
Verify PostgreSQL is running and port 8098 is free (lsof -i :8098). Check logs: docker compose logs engram. Migrations run automatically at boot β they require the engram database to exist (docker/postgres/init/01-create-databases.sql creates it on first compose up).
Rows with NULL embeddings are invisible to the HNSW vector index (it's partial where embedding is not null). If extraction wrote rows without embeddings, recall degrades to flat ~0.34 scores. Fix the embedding pipeline, then backfill with scripts/backfill_embeddings.py.
Every memory also carries an embedding_synthetic flag (v4.0.1): it is set at write time when the deterministic hash fallback produced the vector instead of a real semantic model (a loud WARN is logged, and recall results annotate the flag so consumers can exclude them with exclude_synthetic: true). Run scripts/backfillEmbeddingProvenance.ts to flag historical rows.
Measure recall quality with bun run tsx scripts/recall-eval.ts β a labeled eval harness (cases in scripts/recall-eval-cases.ts) that runs real queries through /recall and reports recall@1/@3/@5 for hybrid and non-hybrid modes. Current store baseline: recall@1 β 0.73, recall@3/@5 = 1.0 (15 cases).
Confirm the Provider settings (Settings tab β Provider, or EG_GENERATIVE_URL / EG_UPSTREAM_LLM_URL / EG_OPENAI_BASE_URL in .env) point to your GPU machine, and use the Settings tab's Test & Save buttons to verify each section live. Note llama-swap must have the embedding model loaded with an embedding-capable router β chat-only model lists 404 on /embeddings.
Compaction runs when a conversation exceeds EG_COMPACT_TRIGGER (code default 50, .env.example 100). Check server logs for the compactionEngine module.
The cron has two tiers (RECENT 4h / DEEP 24h). Trigger manually via POST /api/dashboard/consolidate. Groups come from consolidation_hash with tier-specific minimum sizes (2 recent / 3 deep).
Both engines are schedulers with run locks (manual + scheduled runs never overlap β a concurrent call returns skipped: already in progress). The enrichment engine is flag-first by default (EG_ENRICHMENT_ACTION=flag): it proposes candidates in the Memory Audit ledger and touches nothing until you Apply. Verify enabled state + last run via GET /api/dashboard/enrichment/status and GET /api/dashboard/integrity/status. When the embedding provider is down, engines skip gracefully (the synthetic fallback's 1536-dim vectors fail the 768-dim column check) β no corruption, just no-ops.
node-pg serializes JS arrays as {"0.1","0.2"} (quoted elements), which pgvector's halfvec parser rejects. Embeddings must be bound as JSON strings ([0.1,0.2] β the asVector convention in durable/repository.ts), and provider output should pass through normalizeEmbedding first (some OpenAI-compatible servers return numeric strings). Any new code binding embeddings must follow both.
Compose's environment: block overrides env_file:, and restart doesn't re-read .env. Use docker compose up -d (or docker compose up --build -d after changing the server code) β the container runs a compiled dist/ bundle, so source changes require a rebuild.
The project was previously called OpenMemory and CodeCortex. The official name is FTR10 Engram:
- Engram β Server / core package (
packages/engram-js) - Engram Web GUI β Dashboard interface (
apps/web) - EngramVS β VS Code extension (
apps/vscode-extension)