tonitangpotato/engram-ai/engram-skill

Engram Memory System

Persistent memory with neuroscience-backed retrieval, consolidation, and forgetting. Replaces flat-file MEMORY.md with a searchable, decaying, self-maintaining memory store.

When to Use

• Storing facts, preferences, lessons → add with appropriate type
• Recalling context → recall with natural language query
• Periodic maintenance → consolidate on heartbeat (1-2x/day)
• Feedback loops → reward after user confirms something was helpful/wrong
• Auditing → stats to see memory health

Quick CLI

All commands via the bundled CLI (no MCP required):

# Store a memory
python3 engram-skill/scripts/engram-cli.py add "potato prefers Opus" --type relational --importance 0.7
 
# Recall memories
python3 engram-skill/scripts/engram-cli.py recall "potato preferences" --limit 5
 
# Run consolidation (sleep cycle)
python3 engram-skill/scripts/engram-cli.py consolidate
 
# View stats
python3 engram-skill/scripts/engram-cli.py stats
 
# Export database backup
python3 engram-skill/scripts/engram-cli.py export ./backup.db
 
# Pin/unpin a memory (pinned memories never decay)
python3 engram-skill/scripts/engram-cli.py pin <memory-id>
python3 engram-skill/scripts/engram-cli.py unpin <memory-id>
 
# Forget a specific memory or prune weak ones
python3 engram-skill/scripts/engram-cli.py forget --id <memory-id>
python3 engram-skill/scripts/engram-cli.py forget --prune --threshold 0.01
 
# Apply reward feedback
python3 engram-skill/scripts/engram-cli.py reward "great, that was correct!"

Default database: ./engram.db (override with --db /path/to/file.db).

Python API (Direct)

from engram import Memory
mem = Memory("./agent.db")
# Store
mem.add("potato prefers Opus", type="relational", importance=0.7)
mem.add("Use www.moltbook.com not moltbook.com", type="procedural", importance=0.8)
# Recall — returns list of dicts with confidence scores
results = mem.recall("moltbook URL", limit=5)
for r in results:
    print(f"[{r['confidence_label']}] {r['content']}")
# Consolidate (run daily)
mem.consolidate(days=1.0)
# Stats
mem.stats()  # → dict with counts, layer breakdown, anomaly metrics

Memory Types

Always pick the most specific type. When in doubt, use factual.

Confidence Labels

Recall results include a confidence score (0–1) and human-readable label:

Decision guide:

• certain/confident → use directly
• moderate → use but mention uncertainty if stakes are high
• uncertain/guess → cross-reference or ask the user to confirm

Consolidation Schedule

Run consolidate during heartbeats, ideally 1–2 times per day. This:

1. Decays hippocampal (working) traces
2. Strengthens neocortical (core) traces for important memories
3. Replays archived memories to prevent catastrophic forgetting
4. Runs synaptic downscaling (prevents unbounded growth)

Recommended heartbeat integration:

# In HEARTBEAT.md or heartbeat handler:
python3 engram-skill/scripts/engram-cli.py consolidate

Migration from MEMORY.md

Import existing Clawdbot memory files into Engram:

python3 engram-skill/scripts/migrate-memory.py \
  --memory-dir /Users/potato/clawd \
  --output ./engram.db

This reads MEMORY.md and memory/YYYY-MM-DD.md files, classifies entries, and imports them.

Architecture

Engram is backed by real cognitive science models:

• ACT-R activation for retrieval (frequency × recency power law)
• Memory Chain Model for consolidation (Murre & Chessa 2011)
• Ebbinghaus forgetting curves + interference
• Synaptic Homeostasis (Tononi & Cirelli) for downscaling
• Dopaminergic reward for feedback-driven learning

Memories flow through layers: working → core → archive (like hippocampus → neocortex).