Core Concept

System Architecture

Engram maps every decision you make in an AI interaction directly into a causal graph database. Rather than relying on fuzzy flat vector searches, Engram stores the relationship between your decisions, recording the "why" and explicitly tracking the alternatives you rejected over time.

Dual Database Persistence

  • Neo4j: Stores the structural data mappings and edges. Nodes like Session, Decision, Counterfactual, and Outcome are explicitly linked using edges like CAUSED_BY, SUPERSEDES, and CONTRADICTS.
  • ChromaDB: Allows for fuzzy semantic search. Used as "Level 1" memory to find entry points into the graph utilizing the gemini-embedding-001 encoding format.

The Extraction Pipeline (LangGraph)

When you pipe a conversation or an IDE captures your session via MCP, that text is run through a highly rigid extraction process to distill real knowledge, breaking down long chats into atomic graphs.

  1. Triage Node (Gemini Flash): Inspects the text to determine if it is "High Signal". Removes noise over syntax errors or trivial chat messages so it does not clutter the graph.
  2. Extractor Node (Gemini Pro): Pydantic structured output isolates decisions, finding specifically what alternative was considered and rejected, breaking compound paragraphs into multiple atomic DecisionNodes.
  3. Critique Node (Gemini Flash): Automatically validates the generated decisions for logic consistency. Loops back to extraction if it falls below a 7/10 score.
  4. Graph Writer: Interacts with Neo4j and ChromaDB, resolving context and wiring constraints.

4-Level Retrieval

This is what differentiates Engram from standard RAG applications. During an active engram_context request, we don't just dump flat summaries into the system prompt. Instead, we perform a 4-dimensional traverse to pull optimal context without overflowing the token budget:

Level 1: Semantic Layer

We query ChromaDB for similar decisions based on vector cosine-similarity strings to instantly identify matching root identifiers.

Level 2: Causal Ancestry

We take those matching identifiers and walk upstream inside the Neo4j graph using the CAUSED_BY edges. This answers: "What historical decisions directly led up to this outcome structure?"

Level 3: Full Episode Context

We expand the current node downwards to pull all the reasoning, the exact `rejection_concern` for every connected counterfactual, and subsequent outcomes recorded.

Level 4: Counterfactual Surfaces

We specifically query the Graph for active "Warnings". If an agent is considering a "High Scalability Database Architecture" context, Engram will proactively query Neo4j for previously disconnected Counterfactuals matching "Scalability". Finding past rejections helps prevent repeating mistakes across completely unrelated projects.

The Epistemic Weight Engine

Memory must slowly die unless proven right. Engram accomplishes this inherently using Epistemic Weighting.

Every node has a starting weight of 0.7 logic value.

  • Time Decay: A background process continuously drops the weight of a node over time, relative to its importance. (Architecture choices decay over months, bug fixes over days).
  • Propagation Boost: If a past decision is successfully surfaced via Retrieval and utilized by the AI in code generation, it is artificially boosted closer to 1.0 logic value, solidifying the choice as bedrock engineering design.
  • Override Signals: If Neo4j sees a new architectural node inserted in the exact same domain space as a previous one, it forcefully cuts the weight of the old node entirely effectively creating a SUPERSEDES edge.