Engramai

Neuroscience-grounded memory for AI agents. Add, recall, and manage memories with ACT-R activation, Hebbian learning, and cognitive consolidation.

Security Scan

The skill's instructions broadly match a memory module (requires python and a PyPI package) but contain inconsistencies and guidance that could lead to storing sensitive secrets and running arbitrary package code, so proceed cautiously.

Purpose & Capability

Name and description (neuroscience-grounded memory) match the SKILL.md: it documents an installable Python package, a client API, CLI, and an MCP server. Requiring python3 and a pip package is expected. Minor inconsistencies: SKILL.md claims 'Zero Dependencies' while also instructing 'pip install engramai'; links include both PyPI and an unrelated-sounding npm package which is unusual but possibly indicating multi-language ports.

Instruction Scope

Instructions tell agents to store and recall arbitrary memories, run a local MCP server, and recommend storing high-importance items (example list includes 'API keys location' under critical info). Although SKILL.md also warns against storing sensitive data, the Importance Guide explicitly lists API key locations as 'critical info' — this is contradictory and risks agents storing secrets. Running the MCP server with a writable DB path under ~/.clawdbot is expected for a memory tool, but it does give the package direct read/write access to the agent's memory DB.

Install Mechanism

The skill is instruction-only in the registry (no install spec), but SKILL.md instructs users to 'pip install engramai' (PyPI). Installing a package from PyPI is common and traceable, but it executes third‑party code on the host—there is no packaged install spec or checksum in the registry to verify provenance. No direct red flags like IP download URLs were present.

Credentials

The skill requests no environment variables in metadata, which is reasonable. However, the documentation suggests storing extremely sensitive items (API keys location) at high importance and configuring ENGRAM_DB_PATH to point to the agent DB. That combination could enable the package to access secrets stored in the same DB. The skill does not justify why secrets would be stored or how they would be protected/encrypted.

Persistence & Privilege

always is false and autonomous invocation is allowed (platform default). The MCP server pattern implies the package could be run as a long-lived process that reads/writes the agent DB; this is consistent with a memory service but increases blast radius compared to an ephemeral library. No evidence the skill attempts to modify other skills or system-wide settings.

What to consider before installing

This skill is internally coherent as a memory tool, but there are several things to check before installing or enabling it: 1) Verify the PyPI package and GitHub repository (author identity, recent commits, stars, open issues) and prefer pinned versions and checksums. 2) Inspect the package source (or ask for a code audit) before running pip install, because it will run code on your host and can read/write the agent DB. 3) Don’t store secrets in the memory DB; change the guidance that lists 'API keys location' as storable—keep secrets in a dedicated secret manager and never mark them as normal memories. 4) If running the MCP server, run it in a restricted environment (container or limited user) and ensure the DB file is encrypted or access-limited. 5) Ask the skill author for privacy/security details: whether the DB is encrypted, how rewards/exports handle sensitive fields, and whether the MCP server binds only to localhost. If you need, provide the package name and I can look up the PyPI/GitHub repository and summarize maintainer details and recent code activity.

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

Trigger	Action	Example
Learn user preference	store(type="relational")	"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:

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

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