Engrams

An engram is the fundamental unit of storage in MuninnDB. The term comes from neuroscience — a memory engram is the physical trace left in a neural network when a memory is formed. In MuninnDB, an engram is a structured memory record with cognitive properties built in.

Think of an engram as a "row" that knows:

• How confident we are in the information it contains
• How relevant it is — scored at query time based on recency and access frequency
• What other engrams it's related to, and how strongly
• How many times it's been retrieved (affects stability)

What is an Engram?

Every engram stores a single piece of knowledge — a fact, a preference, a decision, an observation. Unlike database rows, engrams are designed to model how human memory actually works:

• Frequently recalled memories score higher and surface first — temporal priority compounds with access frequency
• Memories that are recalled together build stronger associations over time
• Conflicting memories reduce each other's confidence
• Old, unaccessed memories score lower but are never deleted — total recall is always preserved

Engram Fields

Lifecycle States

Engrams have a lifecycle state that controls how they're treated by the activation engine:

• PLANNING — Draft state. Not yet activated in queries by default.
• ACTIVE — Normal state. Included in ACTIVATE queries.
• PAUSED — Temporarily suspended. Not returned in queries, decay halted.
• BLOCKED — Dependency blocked. Similar to PAUSED.
• COMPLETED — Finished. Can be activated for historical context.
• CANCELLED — Abandoned. Excluded from activation.
• ARCHIVED — Long-term storage. Excluded from normal activation.
• SOFT_DELETED — Marked for deletion. Restorable for 7 days via muninn_restore.

Associations

Every engram can have weighted associations to other engrams. Associations are bidirectional and their weights evolve automatically through Hebbian learning — the more two engrams are retrieved together, the stronger their association becomes.

You can also set associations manually when storing an engram. The association weight is a float between 0.0 and 1.0. During ACTIVATE queries, Phase 5 (Graph Traversal) uses a BFS walk up to depth 2 to surface associated engrams, applying a hop penalty at each depth.

Storing Engrams

client := muninn.NewClient("http://localhost:8475", "your-token")

engID, err := client.Write(ctx, "default",
    "database is PostgreSQL-compatible",
    "The backend uses PostgreSQL 15 with pgvector extension",
    []string{"infrastructure", "database"})

async with MuninnClient("http://localhost:8475", token="your-token") as client:
    eng_id = await client.write(
        vault="default",
        concept="database is PostgreSQL-compatible",
        content="The backend uses PostgreSQL 15 with pgvector extension",
        tags=["infrastructure", "database"],
    )

Reading Engrams

Point reads by ID return a single engram. ACTIVATE queries return the N most cognitively relevant engrams for a given context.

// Point read by ID
e, err := client.Read(ctx, engramID, "default")

// Cognitive activation — finds most relevant engrams
results, err := client.Activate(ctx, "default",
    []string{"what database do we use?"}, 5)

# Point read by ID
e = await client.read(vault="default", engram_id=eng_id)

# Cognitive activation — finds most relevant engrams
results = await client.activate(
    vault="default",
    context=["what database do we use?"])