tonitangpotato/engram-ai/skill

engramai 🧠

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

Installation

pip install engramai

Quick Start

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

# 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

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

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:

## 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:

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

MCP Config (Clawdbot):

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

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