Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Engram β€” Persistent Memory for AI Agents

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.

TypeScript Node.js PostgreSQL Docker


Table of Contents


What Engram Is

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:

  1. 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.
  2. 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).
  3. Compaction engine β€” long conversations are summarized in-place so context windows never grow unbounded.
  4. Consolidation cron ("the hippocampus") β€” a two-tier background job that merges, promotes, and prunes memories to keep the knowledge base healthy.
  5. Trace observability β€” every request/response is captured to a persistent traces store (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.
  6. 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.
  7. 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.
  8. 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.
  9. 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_to edges); 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."
  10. 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.


How It Works

Request lifecycle (POST /v1/chat/completions)

The heart of Engram is the chat-completions route in packages/engram-js/src/api/routes/chat/completions/route.ts. The full flow:

  1. Authenticate & validate β€” x-api-key / Bearer / ApiKey header (public endpoints are only /health, /api/performance/system, /api/performance/llama-swap). An authenticated user_id overrides any client-supplied one (impersonation guard). The session id resolves from x-session-id header β†’ body β†’ query β†’ a deterministic sha256(user_id:project_id) (so all turns of one conversation group automatically).
  2. 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.
  3. 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_trgm keyword 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}.
  4. 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.
  5. 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 and reasoning_content thinking tokens stripped) before injection.
  6. Compact if needed β€” when the sanitized message count exceeds EG_COMPACT_TRIGGER (code default 50, .env.example 100), the compaction engine runs before forwarding (see below).
  7. 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.
  8. Stream back via SSE β€” tokens pipe transparently to the client; Engram's status arrives as valid OpenAI-format chat.completion.chunk deltas, so any OpenAI-compatible client renders it natively: 🧠 Injected 🧬 N genome, 🧠 M memories, πŸ“¦ K facts, 🌐 S sources, then a final _trace payload (the "Engram Memory Trace" shown by the VS Code extension) and data: [DONE].
  9. Extract in the background β€” logInteractionAsync() is fire-and-forget: it never blocks the stream.

Memory extraction & storage

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.

Compaction engine

When a conversation exceeds EG_COMPACT_TRIGGER messages, the compaction engine keeps context bounded (invoked in the request path, before forwarding):

  1. Isolate β€” split into old history + a recent raw tail (EG_MAX_RAW_TURNS, code default 6, .env.example 4); tool-call boundaries are fixed so no orphan tool results break the upstream API; the last user message is preserved for continuity.
  2. Thin β€” truncate oversized tool outputs (>800 chars), assistant responses (>1200), and user messages (>1000); drop consecutive duplicate tool calls.
  3. Summarize & extract in one LLM call β€” the compacted history goes to the generative model, which returns JSON {summary, facts[]} (temperature 0.1, capped at EG_COMPACT_PROMPT_MAX_CHARS).
  4. Save facts β€” extracted facts are stored via rememberDurableMemory with source: "compaction_engine" (one failed save rolls back the batch).
  5. 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.

Consolidation engine ("the hippocampus")

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).

Trace observability (v4.2.0-traces)

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-REAP20 on 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 bad threshold) are flagged needs review until opened (or marked reviewed); the review loop is the human-in-the-loop for judge output.
  • Report β€” POST /api/dashboard/traces/report aggregates 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).

Judge governance (v4.3.0-governance)

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_calibration table; the GUI lets you add any trace with your expected score). POST /api/dashboard/judge/run-calibration re-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/consistency re-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.

Integrity engine (auto-heal, v4.4.0-integrity)

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, or delete (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).

Enrichment engine (auto-optimization, v4.5.0-optimization)

The third rung: it takes the memories the user actually uses that are weakest and improves them with sourced evidence, never rewriting in place:

  1. Selection β€” pool = semantic/procedural, active, embedded, never genome (column OR metadata.is_genome) and never intent/TODO/preference content (deterministic isIntentOrTodo gate β€” "user wants to…", "needs updating", "should…", "remind…"), ordered by usage; a completeness-rubric judge call scores the batch (0 = complete, 1 = critically incomplete).
  2. Sources, in order β€” (a) the store itself (related memories β‰₯ 0.85 sim), (b) codebase β€” rg over 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.
  3. 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).
  4. 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 earns apply back) or apply.

Audit trail + undo (v4.4.0)

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.

Memory coherence engine ("the living skill", v4.6.0-coherence)

The rung that fixes the "Important decision: restructure conditional rendering…" class β€” memories that are context-free because extraction dropped the specifics. Two halves:

  1. 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_fidelity judge dimension.
    • Links β€” extraction emits links: [{from, to, type}] (part_of / derives_from / related_to only); the write path materializes them as edges rows. Unsupported link types β†’ cluster_link_evaluation findings for judge/user (a memory is never dropped because it couldn't be linked β€” new projects start unlinked clusters, which is fine).
  2. Recall (the bundle) β€” POST /api/memories/bundle?topic=X (and auto-detection in /api/cognitive-context for "working on X" phrases): clusterEngine finds 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 #9 broken_links (edges whose endpoint memory is superseded β€” the graph can't rot silently).

Repo baseline index engine (v4.7.0-repo-index)

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:

  1. 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.
  2. 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.
  3. Discipline preserved β€” every memory carries metadata.repo (the canonical identity: owner/repo for 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.
  4. 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.
  5. 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), toggle EG_REPO_AUTO_REFRESH, manual POST /api/dashboard/repos/refresh.

Memory decay engine

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_tier transitions (active/warm/cold/archived). The decay job runs via POST /admin/decay/run.

Memory Model: Genome & Phenotype

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.

Phenotype Sectors

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"

Architecture

Engram architecture diagram

πŸ“ 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
Loading

Project Structure

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).


Quick Start (Docker)

# Build and start everything
docker compose up --build -d

# Check status
docker compose ps

# View logs
docker compose logs -f engram

Services

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 & Clean

# Stop all services
docker compose down

# Stop and remove all data volumes (fresh start)
docker compose down -v

Client Configuration

Point 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.

Engram for VS Code (apps/vscode-extension)

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/activity for live traffic in the status bar / Dashboard panel
  • Tracks IDE sessions (/api/ide/session/start|end, /api/ide/events) and exposes engram.queryContext / engram.addToMemory
  • Registers the @cortex chat participant, which forwards prompts through Engram and renders the collapsible "🧠 Engram Memory Trace" from the _trace SSE payload

Hermes sidecar (Option B)

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() calls POST /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 /recall on Engram builds without the route.
  • After each turn β†’ sync_turn() hands the turn (user message + assistant reply) to POST /ingest/conversation so Engram's extraction LLM decides what to store (genome promotion is explicitly disabled for chat turns β€” genome is reserved for explicit engram_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_contradiction tools.
  • The plugin lives at apps/hermes-plugin/ (copied to ~/.hermes/plugins/engram/); activate with hermes config set memory.provider engram. No MCP server β€” stdlib urllib only.

Configuration

Where configuration lives

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.

Model resolution

All models resolve through src/database/modelRegistry.ts, in one order:

  1. Settings tab (Postgres app_settings) β€” per-task / per-facet / master values
  2. Env override (legacy vars above)
  3. Fail with a clear message (never a silent hardcoded model name)
  • Generative β€” resolveGenerativeModel(task) for extraction, compaction, consolidation, or default (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_KEY fallbacks. Used for trace scoring, false-memory sampling, and the enrichment completeness/grounding/compose/validate rubrics.
  • Embedding β€” resolveEmbeddingModel(facet) for episodic/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 (flagged embedding_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).


Local Development (No Docker)

# 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 start

Migrations 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.


Web GUI

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 (.env values); 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 build

API Overview

The 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

Troubleshooting

Common issues

Server won't start

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).

Recall returns flat / low scores

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).

Cannot reach upstream LLM

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 not triggering

Compaction runs when a conversation exceeds EG_COMPACT_TRIGGER (code default 50, .env.example 100). Check server logs for the compactionEngine module.

Consolidation not running

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).

Enrichment / integrity engines not acting

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.

"invalid input syntax for type halfvec" errors

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.

.env changes not picked up after docker compose restart

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.


Naming

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)

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages