Architecture

The Four Layers

Engrammic organizes knowledge into cognitive layers, each with different trust levels and evidence requirements.

Memory

Raw observations. No evidence required, low commitment.

Tools: remember

Example: "User said they prefer functional components"

Memories decay over time if not reinforced. They are the starting point, not the destination.

Knowledge

Verified claims with evidence. The evidence can be a file, URL, or reference to another node.

Tools: learn

Example: "Project uses esbuild for bundling" (evidence: README.md, package.json)

Knowledge nodes require evidence. This is what separates "I heard" from "I verified."

Wisdom

Conclusions drawn from knowledge. Beliefs link to the nodes they are based on.

Tools: believe

Example: "Team values build performance" (based on: esbuild choice, CI optimization discussion)

Wisdom nodes create edges to their supporting knowledge, forming a traceable reasoning chain.

Intelligence

Active reasoning during a session. Hypotheses are tentative beliefs that can be revised before committing.

Tools: hypothesize, revise, commit

How Data Flows

Each layer builds on the one below. Wisdom without Knowledge is speculation. Knowledge without evidence is rumor.

Supersession Pattern

When knowledge changes, Engrammic does not delete or duplicate. It creates version chains.

Query current state: Returns v3

Query history: Returns the full chain with timestamps

Why this matters: You can answer "what do we know now?" and "how did we get here?" from the same graph.

How to Supersede

When storing, recall first to check for existing knowledge:

1. recall("API authentication")
2. Found node abc123: "Uses OAuth2"
3. learn("Uses OAuth2 with PKCE", evidence=[...], supersedes="abc123")

The old node remains for history. The new node becomes current.

Graph Relationships

Nodes connect via typed edges:

Use link to create relationships manually. SAGE creates them automatically during synthesis.

Services Architecture

Engrammic runs several services that work together:

How Recall Works

When you call recall, Engrammic combines multiple retrieval strategies:

1. Semantic search (Qdrant) -- find nodes with similar meaning
2. Keyword search -- exact term matching
3. Graph traversal (Memgraph) -- follow relationships from initial hits
4. Fusion -- combine and rerank results

This is why Engrammic can answer questions that require connecting concepts, not just finding similar text.

What SAGE Does

SAGE runs in the background:

• Deduplication: Clusters similar memories, promotes to knowledge
• Synthesis: Identifies patterns across facts, proposes beliefs
• Contradiction detection: Flags conflicting nodes for review
• Staleness detection: Marks commitments that may need revisiting

SAGE proposes; the agent decides. Use believe to form a conclusion, dismiss to reject a marker.

Meta-Memory

Cross-cutting capabilities that span all layers:

• Provenance: Every node tracks where it came from
• Time-travel: Query state at any point in history
• Reflection: reflect stores observations about your own beliefs

This is what makes "why do you believe that?" answerable.