2530 Engram Specification 4a2954e4

Engram Specification: The Cognitive Memory Model

Version: 1.0.0
Status: CANONICAL
Category: Agent Control Plane / Memory

Executive Summary

Engrams are the atomic units of contextual memory in Nucleus. Unlike generic "memory" systems, Engrams encode strategic context with intensity levels, zoom-based categorization, and optional cryptographic signatures for sovereignty.

1. Data Model

Engram Schema

class Engram:
    key: str           # Unique identifier (e.g., "auth_architecture")
    value: str         # The remembered content
    context: str       # Zoom level category (Feature, Architecture, Brand)
    intensity: int     # 1-10 priority scale (how much should the agent care?)
    timestamp: str     # ISO 8601 creation time
    signature: str     # Optional: Cryptographic signature for sovereignty

JSON Representation

{
  "key": "flask_session_decision",
  "value": "Using Flask-Session with Redis backend for stateless scaling",
  "context": "Architecture",
  "intensity": 8,
  "timestamp": "2026-01-26T10:30:00Z",
  "signature": null
}

2. Context Categories (Zoom Levels)

Engrams are organized by strategic "zoom level" to enable efficient retrieval:

3. Intensity Scale

The intensity level (1-10) indicates how much attention the agent should give to this Engram:

Intensity Guidelines

10: "NEVER use OpenAI API - budget constraint"
 8: "All new features need unit tests"
 5: "Prefer Tailwind over raw CSS"
 3: "Old logo was blue, changed to purple in v2"
 1: "Considered MongoDB in 2024, rejected"

4. Storage Format

Ledger Location

.brain/
├── engrams/
│   └── ledger.jsonl    # Append-only Engram storage

JSONL Format

Each line is a complete Engram:

{"key": "api_auth", "value": "JWT tokens with 24h expiry", "context": "Architecture", "intensity": 7, "timestamp": "2026-01-20T08:00:00Z", "signature": null}
{"key": "color_scheme", "value": "Purple primary (#7C3AED)", "context": "Brand", "intensity": 5, "timestamp": "2026-01-21T14:30:00Z", "signature": null}
{"key": "no_openai", "value": "Do not use OpenAI - Gemini only", "context": "Decision", "intensity": 10, "timestamp": "2026-01-22T09:15:00Z", "signature": null}

5. Query Patterns

Query by Context

from memoir.engram import EngramLedger
from pathlib import Path

ledger = EngramLedger(Path(".brain"))

# Get all Architecture engrams
arch_engrams = ledger.query_context("Architecture")

# Sorted by intensity (highest first)
for e in arch_engrams:
    print(f"[{e.intensity}] {e.key}: {e.value}")

Query All

# Get complete memory
all_engrams = ledger.query_all()
print(f"Total engrams: {len(all_engrams)}")

Keyword Search (via context matching)

# Searches key, value, and context fields
results = ledger.query_context("JWT")

6. Write Patterns

Creating an Engram

from memoir.engram import Engram, EngramLedger
from pathlib import Path

ledger = EngramLedger(Path(".brain"))

# Create high-intensity architectural decision
engram = Engram(
    key="database_choice",
    value="PostgreSQL for production, SQLite for local dev",
    context="Architecture",
    intensity=8
)

ledger.write_engram(engram)

Intensity Guidelines for Writing

7. Cryptographic Sovereignty (Future)

Planned Features (v0.6.0+)

1. Signing: Each Engram can be cryptographically signed by the owner
2. Verification: Agents can verify Engram authenticity before trusting
3. Export: Signed Engrams can be safely exported/shared

Signature Schema (Planned)

{
  "key": "critical_decision",
  "value": "...",
  "context": "Strategy",
  "intensity": 10,
  "timestamp": "2026-01-26T10:30:00Z",
  "signature": {
    "algorithm": "ed25519",
    "public_key": "...",
    "signature": "..."
  }
}

8. Integration with MCP Tools

Related Tools

Future Tool (Planned)

@mcp.tool()
def brain_write_engram(key: str, value: str, context: str, intensity: int = 5) -> str:
    """Write a new Engram to the cognitive memory ledger."""
    # Implementation

9. Best Practices

DO

• ✅ Use high intensity (8-10) for constraints and critical decisions
• ✅ Use descriptive keys (e.g., "auth_jwt_expiry" not "auth1")
• ✅ Include reasoning in value (e.g., "X because Y")
• ✅ Use consistent context categories

DON'T

• ❌ Store secrets or API keys in Engrams
• ❌ Use intensity 10 for everything (defeats the purpose)
• ❌ Create duplicate keys (update existing instead)
• ❌ Store large binary data

10. Comparison with Other Memory Systems

Related Documents

• GOVERNANCE_POLICIES.md - Security model
• RECURSIVE_AGGREGATOR.md - Architecture
• memoir/engram.py - Implementation

Part of the Nucleus Sovereign OS (N-SOS) documentation.
Generated: January 26, 2026