engramai 🧠

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

Installation

CODEBLOCK0

Quick Start

CODEBLOCK1

CLI Usage

CODEBLOCK2

AI Agent Integration (Important!)

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

When to Call What

Trigger	Action	Example
Learn user preference	INLINECODE0	"User prefers concise answers"
Learn important fact

store(type="factual") | "Project uses Python 3.12" | | Learn how to do something | store(type="procedural") | "Deploy requires running tests first" | | Question about history | recall() first, then answer | "What did I say about X?" | | User satisfied | reward("positive feedback") | Strengthens recent memories | | User unsatisfied | reward("negative feedback") | Suppresses recent memories | | Daily maintenance | consolidate() + 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

Level	Use For
0.9-1.0	Critical info (API keys location, absolute preferences)
0.7-0.8

Important (code style, project structure) | | 0.5-0.6 | Normal (general facts, experiences) | | 0.3-0.4 | Low 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:

CODEBLOCK3

Memory Types

• - factual — Facts and knowledge
• INLINECODE9 — Events and experiences
• INLINECODE10 — Relationships and preferences
• INLINECODE11 — Emotional moments
• INLINECODE12 — How-to knowledge
• INLINECODE13 — Beliefs and opinions

MCP Server

For Claude/Cursor/Clawdbot integration:

CODEBLOCK4

MCP Config (Clawdbot):

CODEBLOCK5

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

Key Features

Feature	Description
ACT-R Activation	Retrieval ranked by recency × frequency × context
Memory Chain

Dual-system consolidation (working → core) | | Ebbinghaus Forgetting | Natural decay with spaced repetition | | Hebbian Learning | "Neurons that fire together wire together" | | Confidence Scoring | Metacognitive monitoring | | Reward Learning | User feedback shapes memory | | Zero Dependencies | Pure 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