engramai 🧠#

Cognitive memory system implementing ACT-R activation, Memory Chain consolidation, Ebbinghaus forgetting, and Hebbian learning.

Installation#

bash

pip install engramai

Quick Start#

python

from engram import Memory

mem = Memory("./agent.db")
mem.add("User prefers concise answers", type="relational", importance=0.8)
results = mem.recall("user preferences", limit=5)
mem.consolidate()  # Daily maintenance

CLI Usage#

bash

# Add a memory
neuromem add "User prefers dark mode" --type preference --importance 0.8

# Recall memories
neuromem recall "user preferences"

# View statistics
neuromem stats

# Run consolidation (like sleep)
neuromem consolidate

# Prune weak memories
neuromem forget --threshold 0.01

# List memories
neuromem list --limit 20

# Show Hebbian links
neuromem hebbian "dark mode"

AI Agent Integration (Important!)#

For AI agents to use engram correctly, follow these patterns:

When to Call What#

TriggerActionExampleLearn user preferencestore(type="relational")"User prefers concise answers"Learn important factstore(type="factual")"Project uses Python 3.12"Learn how to do somethingstore(type="procedural")"Deploy requires running tests first"Question about historyrecall() first, then answer"What did I say about X?"User satisfiedreward("positive feedback")Strengthens recent memoriesUser unsatisfiedreward("negative feedback")Suppresses recent memoriesDaily maintenanceconsolidate() + forget()Run via cron or heartbeat

What to Store#

✅ Store:

• User preferences and habits
• Important facts and decisions
• Lessons learned
• Procedural knowledge

❌ Don't store:

• Every conversation message (too noisy)
• Temporary information
• Publicly available facts
• Sensitive data (unless requested)

Importance Guide#

LevelUse For0.9-1.0Critical info (API keys location, absolute preferences)0.7-0.8Important (code style, project structure)0.5-0.6Normal (general facts, experiences)0.3-0.4Low priority (casual chat, temp notes)

Hybrid Mode (Recommended)#

Use engram alongside file-based memory:

• engram: Active memory — retrieval, associations, dynamic weighting
• Files (memory/*.md): Logs — transparency, debugging, manual editing

Heartbeat Maintenance#

Add to your heartbeat or cron:

markdown

## Memory Maintenance (Daily)
- [ ] engram.consolidate
- [ ] engram.forget --threshold 0.01

Memory Types#

• factual — Facts and knowledge
• episodic — Events and experiences
• relational — Relationships and preferences
• emotional — Emotional moments
• procedural — How-to knowledge
• opinion — Beliefs and opinions

MCP Server#

For Claude/Cursor/Clawdbot integration:

bash

python -m engram.mcp_server --db ./agent.db

MCP Config (Clawdbot):

yaml

mcp:
  servers:
    engram:
      command: python3
      args: ["-m", "engram.mcp_server"]
      env:
        ENGRAM_DB_PATH: ~/.clawdbot/agents/main/memory.db

Tools: engram.store, engram.recall, engram.consolidate, engram.forget, engram.reward, engram.stats, engram.export

Key Features#

FeatureDescriptionACT-R ActivationRetrieval ranked by recency × frequency × contextMemory ChainDual-system consolidation (working → core)Ebbinghaus ForgettingNatural decay with spaced repetitionHebbian Learning"Neurons that fire together wire together"Confidence ScoringMetacognitive monitoringReward LearningUser feedback shapes memoryZero DependenciesPure Python stdlib + SQLite

Links#

• PyPI: https://pypi.org/project/engramai/
• npm: https://www.npmjs.com/package/neuromemory-ai
• GitHub: https://github.com/tonitangpotato/neuromemory-ai
• Docs: https://github.com/tonitangpotato/neuromemory-ai/blob/main/docs/USAGE.md