Skip to main content

Neuroscience-grounded memory for AI agents

Project description

neuromemory-ai ๐Ÿง 

Neuroscience-grounded memory for AI agents

engram /หˆษ›nษกrรฆm/ โ€” a hypothesized physical trace in the brain that stores a memory. First proposed by Richard Semon (1904), the engram represents the idea that experiences leave lasting biological changes in neural tissue. We chose this name because, like its neuroscience namesake, this library treats memories not as static records but as living traces that strengthen, fade, and interact over time.

PyPI npm License Python TypeScript Dependencies


neuromemory-ai gives AI agents memory that actually works โ€” using real mathematical models from cognitive science instead of naive embeddings and cosine similarity.

from engram import Memory

mem = Memory("./agent.db")
mem.add("Alice prefers functional programming", type="relational", importance=0.7)
mem.add("Always validate input before DB queries", type="procedural", importance=0.9)

results = mem.recall("coding best practices", limit=3)
mem.consolidate()  # Run "sleep" โ€” transfers short-term โ†’ long-term memory

Zero required dependencies. Optional embedding support. SQLite storage. Works offline.


Why Engram?

Every AI agent framework bolts on memory as an afterthought. The typical approach:

  1. Embed text into vectors
  2. Store in a vector database
  3. Retrieve by cosine similarity
  4. Hope for the best

This ignores everything we know about how memory actually works. Human memory isn't a search engine โ€” it's a dynamic system where memories strengthen through use, fade without it, compete with each other, and consolidate during rest.

The result? Agents that:

  • Retrieve irrelevant memories because they're semantically similar but contextually wrong
  • Never forget anything, drowning in noise as memory grows
  • Can't distinguish between important lessons and trivial observations
  • Treat a memory from 6 months ago the same as one from 5 minutes ago

Evaluation

We evaluated engram on two benchmarks measuring different capabilities:

Semantic Retrieval (LoCoMo)

LoCoMo is a third-party benchmark with 1,982 questions testing conversational memory retrieval.

Method MRR Hit@5
FTS5-only (no embeddings) 0.011 1.6%
Embedding-only (BGE-small) 0.255 38.9%

When using embeddings for semantic retrieval, engram achieves MRR 0.255 โ€” competitive with embedding-based memory systems.

Temporal Dynamics (TDB)

We created a Temporal Dynamics Benchmark to evaluate what ACT-R specifically addresses: recency, frequency, and importance-based retrieval.

Method Recency Override Frequency Importance Overall
Cosine-only 0% 18% 50% 22%
Recency-only 20% 18% 20% 20%
ACT-R 60% 100% 100% 80%

On temporal dynamics tasks, ACT-R achieves 80% accuracy vs ~20% for approaches without temporal weighting.

Key insight: Semantic retrieval and temporal reasoning are different problems. Use embeddings to find relevant memories; use ACT-R to prioritize based on recency, frequency, and importance.

โš ๏ธ Note on TDB: This benchmark was created by us to evaluate temporal dynamics โ€” a dimension not covered by existing benchmarks. The methodology and code are open source for independent validation.


The Science

LLMs are already the semantic layer. When you need semantic matching, use embeddings. What ACT-R adds is mathematical rigor in temporal dynamics โ€” when to surface recent vs. old, frequent vs. rare, important vs. trivial.

Engram implements actual peer-reviewed models from cognitive science:

Model What it does Paper
ACT-R Retrieval scoring via activation (recency ร— frequency ร— context) Anderson et al.
Memory Chain Dual-system consolidation (working โ†’ core memory) Murre & Chessa, 2011
Ebbinghaus Forgetting curves with spaced repetition Ebbinghaus, 1885

The math is simple. The insight is connecting it to agent memory. Total core: ~500 lines of Python.

Features

  • ๐Ÿงฎ ACT-R activation scoring โ€” retrieval ranked by recency ร— frequency ร— context match (not cosine similarity)
  • ๐Ÿ”„ Memory consolidation โ€” dual-system transfer from working memory to core memory, with interleaved replay
  • ๐Ÿ“‰ Ebbinghaus forgetting โ€” memories decay naturally; spaced repetition increases stability
  • ๐Ÿท๏ธ 6 memory types โ€” factual, episodic, relational, emotional, procedural, opinion โ€” each with distinct decay rates
  • ๐ŸŽฏ Confidence scoring โ€” metacognitive monitoring tells you how much to trust each retrieval
  • ๐Ÿ’Š Reward learning โ€” positive/negative feedback strengthens or suppresses recent memories
  • โš–๏ธ Synaptic downscaling โ€” global normalization prevents unbounded memory growth
  • โš ๏ธ Anomaly detection โ€” flags unusual patterns (predictive coding)
  • ๐Ÿ“Œ Pinning โ€” manually protect critical memories from decay
  • ๐Ÿ—„๏ธ SQLite + FTS5 โ€” persistent storage with full-text search, zero config
  • ๐Ÿ”€ Contradiction detection โ€” memories can contradict each other; outdated memories get 0.3ร— confidence penalty
  • ๐Ÿ” Graph search โ€” entity-linked memories with multi-hop graph expansion
  • ๐Ÿง  Hebbian learning โ€” "neurons that fire together wire together" โ€” automatic link formation from co-activation patterns (no NER needed)
  • โš™๏ธ Config presets โ€” tuned parameter sets for chatbot, task-agent, personal-assistant, researcher
  • ๐Ÿ“ฆ Zero required dependencies โ€” pure Python stdlib for FTS5 mode. Optional embedding adapters for semantic search.
  • ๐Ÿ”Œ Pluggable embeddings โ€” supports OpenAI, sentence-transformers, or custom adapters.

What You Need

Just Python 3.10+ and your existing LLM.

NeuromemoryAI works in two modes:

FTS5 Mode (Zero Dependencies)

from engram import Memory
mem = Memory("./agent.db")  # Pure Python, no external services

Best for: Fast prototyping, offline use, when your LLM handles semantic matching.

Embedding Mode (Recommended for Production)

from engram import Memory
from engram.embeddings import SentenceTransformerAdapter

mem = Memory("./agent.db", embedding=SentenceTransformerAdapter())

Best for: Production deployments needing semantic retrieval. Supports OpenAI, sentence-transformers, or any embedding provider.

The key insight: Embeddings handle semantic matching; ACT-R handles temporal dynamics. Use both for optimal retrieval.

Quick Comparison

Without neuromemory-ai With neuromemory-ai
โŒ "What's your name again?" โœ… "I remember you're Alice, you prefer Python"
โŒ Retrieves irrelevant old memories โœ… Recent memories prioritized via ACT-R
โŒ Memory grows unbounded โœ… Natural forgetting keeps signal-to-noise high
โŒ Can't distinguish important from trivial โœ… Importance weights consolidation
โŒ No learning from co-occurrence โœ… Hebbian links form from usage patterns

5-Minute Quickstart

1. Install

Platform Install Documentation
Python pip install neuromemory-ai PyPI
TypeScript npm install neuromemory-ai npm
MCP Server python -m engram.mcp_server MCP Setup
CLI neuromem --help CLI Docs

2. Basic Usage (standalone)

from engram import Memory

# Create/open a memory database (SQLite file)
mem = Memory("./my-agent.db")

# Store memories with type and importance
mem.add("User prefers concise answers", type="relational", importance=0.8)
mem.add("API key is in environment variable", type="procedural", importance=0.9)
mem.add("Had a good conversation about ML today", type="episodic", importance=0.5)

# Recall relevant memories (ranked by ACT-R activation)
results = mem.recall("how should I respond to user?", limit=3)
for r in results:
    print(f"[{r['confidence_label']}] {r['content']}")

# Run daily maintenance (like sleep)
mem.consolidate()  # Transfers working โ†’ core memory
mem.forget()       # Prunes weak memories

3. Integrate with Your Bot

Engram works with any LLM or bot framework. Here's the pattern:

from engram import Memory
from openai import OpenAI  # or anthropic, or local model, or whatever

mem = Memory("./agent.db")
client = OpenAI()

def chat(user_message: str) -> str:
    # 1. Recall relevant memories
    memories = mem.recall(user_message, limit=5)
    memory_context = "\n".join([f"- {m['content']}" for m in memories])
    
    # 2. Build prompt with memory context
    messages = [
        {"role": "system", "content": f"You have these memories:\n{memory_context}"},
        {"role": "user", "content": user_message}
    ]
    
    # 3. Call your LLM
    response = client.chat.completions.create(model="gpt-4", messages=messages)
    reply = response.choices[0].message.content
    
    # 4. Store new memories from conversation
    mem.add(f"User asked: {user_message}", type="episodic", importance=0.3)
    # Extract facts, preferences, etc. and store with higher importance
    
    return reply

def on_feedback(feedback: str):
    # 5. Learn from user feedback
    mem.reward(feedback)  # "great answer!" strengthens, "wrong!" suppresses

4. Choose Your Preset

Different agents need different memory profiles:

from engram.config import MemoryConfig

# Chatbot: remembers everything, slow decay
mem = Memory("bot.db", config=MemoryConfig.chatbot())

# Task agent: fast decay, focused on recent procedural knowledge
mem = Memory("worker.db", config=MemoryConfig.task_agent())

# Personal assistant: long-term memory, relationships matter
mem = Memory("assistant.db", config=MemoryConfig.personal_assistant())

# Researcher: never forgets, archives everything
mem = Memory("research.db", config=MemoryConfig.researcher())

5. Hebbian Learning (Automatic Associations)

Memories that are recalled together automatically form links โ€” no manual entity tagging needed:

# Add memories (no manual entities specified)
mem.add("Python is great for machine learning")
mem.add("PyTorch is my favorite ML framework")
mem.add("TensorFlow has better production support")

# Query multiple times โ€” co-activation creates associations
for _ in range(3):
    mem.recall("machine learning frameworks", limit=3)

# After 3+ co-activations, Hebbian links form automatically
# Now querying "Python" will automatically surface PyTorch/TensorFlow via spreading activation
results = mem.recall("Python tools", graph_expand=True)
# Returns: PyTorch, TensorFlow (via Hebbian links) + Python (direct match)

"Neurons that fire together, wire together" โ€” implemented as associative memory that emerges from usage patterns.

6. Daily Maintenance (cron job or scheduler)

# Run once per day
mem.consolidate()  # Sleep cycle: decay working memory, strengthen core
mem.forget()       # Remove memories below threshold
mem.downscale()    # Prevent runaway activation (synaptic homeostasis)

That's it. Your agent now has biologically-inspired memory that strengthens with use, fades naturally, and responds to feedback.

7. CLI (Command Line Interface)

After installation, use the neuromem command:

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

# Recall memories
neuromem recall "user preferences"

# View statistics
neuromem stats

# Run maintenance
neuromem consolidate
neuromem forget --threshold 0.01

# List all memories
neuromem list --limit 20

# Show Hebbian links for a memory
neuromem hebbian "dark mode"

# Export database
neuromem export backup.db

# Use a different database
neuromem --db ./custom.db add "Custom memory"

Quick Start

pip install neuromemory-ai
from engram import Memory

mem = Memory("./my-agent.db")

# Store with type and importance
mem.add("The deploy key is in 1Password", type="procedural", importance=0.8)
mem.add("User seemed frustrated about the API latency", type="emotional", importance=0.7)

# Recall โ€” ranked by ACT-R activation, not cosine similarity
results = mem.recall("deployment", limit=5)
for r in results:
    print(f"[{r['confidence_label']}] {r['content']}")
    # [certain] The deploy key is in 1Password

# Consolidate โ€” run periodically (like "sleep")
mem.consolidate()

# Feedback shapes future memory
mem.reward("perfect, that's exactly what I needed!")

How It Works

ACT-R Activation (Retrieval)

Every memory has an activation level that determines how quickly and reliably it can be retrieved:

A = B + C + I
  • B (base-level) = ln(ฮฃ t_k^(-0.5)) โ€” power law of practice and recency. Access a memory more often and more recently โ†’ higher activation.
  • C (context) = spreading activation from current query keywords
  • I (importance) = emotional/importance modulation (amygdala analog)

This replaces cosine similarity with a formula that naturally handles recency, frequency, and context โ€” the same way human memory works.

Memory Chain Model (Consolidation)

Memories exist as two traces that evolve over time:

drโ‚/dt = -ฮผโ‚ ยท rโ‚              (working memory decays fast)
drโ‚‚/dt = ฮฑ ยท rโ‚ - ฮผโ‚‚ ยท rโ‚‚     (core memory grows from working, decays slowly)
  • rโ‚ (working_strength) โ€” hippocampal trace. Strong initially, fades in days.
  • rโ‚‚ (core_strength) โ€” neocortical trace. Grows during consolidation, lasts months.
  • consolidate() runs one cycle: decay rโ‚, transfer to rโ‚‚, replay old memories.

Important memories consolidate faster (importance modulates ฮฑ). This is why emotional events are remembered better โ€” the amygdala enhances hippocampal encoding.

Ebbinghaus Forgetting

Retrievability follows the classic forgetting curve:

R(t) = e^(-t/S)

Stability S grows with each successful retrieval (spaced repetition effect) and is modulated by importance and memory type. Procedural memories (how-to knowledge) have 10ร— the base stability of episodic memories (events).

Additional Systems

  • Reward learning โ€” user feedback acts as a dopaminergic signal, strengthening (positive) or suppressing (negative) recently active memories
  • Synaptic downscaling โ€” periodic global normalization (Tononi & Cirelli's SHY) prevents runaway strength accumulation
  • Anomaly detection โ€” rolling baseline tracker flags unusual patterns using z-score deviation (simplified predictive coding)

Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚           Memory (public API)               โ”‚
โ”‚   add() ยท recall() ยท consolidate() ยท ...    โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  L2: CORE        โ”‚ Always loaded. Distilled โ”‚
โ”‚  (high core_str) โ”‚ knowledge. Slow decay.   โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  L3: WORKING     โ”‚ Recent memories. Fast    โ”‚
โ”‚  (high work_str) โ”‚ decay. Being consolidatedโ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  L4: ARCHIVE     โ”‚ Old/weak memories. On-   โ”‚
โ”‚  (low strength)  โ”‚ demand retrieval via FTS โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  SQLiteStore + FTS5 (persistent backend)    โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  activation โ”‚ consolidation โ”‚ forgetting    โ”‚
โ”‚  confidence โ”‚ reward        โ”‚ downscaling   โ”‚
โ”‚  anomaly    โ”‚ search        โ”‚               โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Memories flow: L3 (working) โ†’ L2 (core) โ†’ L4 (archive) as they consolidate and eventually decay. Strong, frequently-accessed memories live in L2 indefinitely. Weak memories fade to L4 and become searchable-only.

Engram vs Mem0 vs Zep

All three are designed for LLM agents โ€” the comparison is about what additional infrastructure each requires beyond the LLM you already have.

Engram Mem0 Zep
Retrieval model ACT-R activation (recency ร— frequency ร— context) Cosine similarity Cosine similarity + MMR
Forgetting Ebbinghaus curves, type-aware decay None (manual deletion) TTL-based expiry
Consolidation Memory Chain Model (working โ†’ core transfer) None None
Memory types 6 types with distinct decay rates Untyped Untyped
Confidence scores Yes (metacognitive monitoring) No No
Reward learning Yes (dopaminergic feedback) No No
Associative links Hebbian learning (automatic co-activation) Manual graph construction None
Additional infra None (SQLite file) Embedding API + Vector DB Embedding API + Postgres
Extra API calls 0 per recall 1+ (embedding) 1+ (embedding)
Works offline โœ… (with local LLM) โŒ โŒ
Math grounding Peer-reviewed cognitive science Engineering heuristics Engineering heuristics
Core code ~500 lines ~5,000+ lines ~10,000+ lines

Engram's thesis: Your LLM already understands semantics โ€” that's what language models do. Memory infrastructure should handle dynamics (when to surface, what to forget, how associations form) using proven cognitive science models, not re-implement semantic understanding with a separate embedding pipeline.

MCP Server

Engram ships with an MCP (Model Context Protocol) server for use with Claude, Clawdbot, or any MCP-compatible client.

# Start the MCP server
python -m engram.mcp_server --db ./agent.db

MCP server provides 7 tools: store, recall, consolidate, forget, reward, stats, export.

API Reference

Memory(path)

Create or open a memory database.

mem = Memory("./agent.db")      # Persistent SQLite file
mem = Memory(":memory:")         # In-memory (non-persistent)

mem.add(content, type, importance, source, tags) โ†’ str

Store a memory. Returns the memory ID.

mid = mem.add(
    "The production database is on us-east-1",
    type="factual",       # factual|episodic|relational|emotional|procedural|opinion
    importance=0.6,       # 0-1, or auto-assigned by type
    source="deploy-doc",  # optional source identifier
    tags=["aws", "prod"], # optional tags
)

mem.recall(query, limit, context, types, min_confidence) โ†’ list[dict]

Retrieve memories ranked by ACT-R activation.

results = mem.recall(
    "database location",
    limit=5,
    context=["production", "aws"],  # Boost spreading activation
    types=["factual", "procedural"],  # Filter by type
    min_confidence=0.3,  # Skip low-confidence results
)

for r in results:
    r["id"]                # Memory ID
    r["content"]           # Memory text
    r["type"]              # Memory type
    r["confidence"]        # 0-1 confidence score
    r["confidence_label"]  # "certain" | "likely" | "uncertain" | "vague"
    r["strength"]          # Effective strength (trace ร— retrievability)
    r["activation"]        # ACT-R activation score
    r["age_days"]          # Days since creation
    r["layer"]             # "core" | "working" | "archive"
    r["importance"]        # 0-1 importance

mem.consolidate(days=1.0)

Run a consolidation cycle. Call periodically (daily, or after learning sessions).

mem.consolidate()        # 1-day cycle
mem.consolidate(days=7)  # Simulate a week of consolidation

mem.reward(feedback)

Apply feedback as a reward signal to recent memories.

mem.reward("perfect, exactly right!")   # Strengthens recent memories
mem.reward("no, that's wrong")          # Suppresses recent memories

mem.forget(memory_id=None, threshold=0.01)

Forget a specific memory or prune all weak memories.

mem.forget("abc123")        # Forget specific memory
mem.forget(threshold=0.05)  # Prune all below threshold

mem.pin(memory_id) / mem.unpin(memory_id)

Pin/unpin a memory. Pinned memories never decay.

mem.update_memory(old_id, new_content) โ†’ str

Correct a memory. Creates a new memory linked to the old one (correction chain).

new_id = mem.update_memory(old_id, "Actually, the database is on us-west-2")
# Old memory is marked as contradicted, new one references it

mem.add(..., contradicts=old_id)

Explicitly mark a new memory as contradicting an old one.

mem.add("We migrated to PlanetScale", type="factual", contradicts=old_id)
# Old memory gets 0.3ร— confidence penalty in recall

Memory(path, config=MemoryConfig.personal_assistant())

Use a config preset tuned for your agent type.

from engram.config import MemoryConfig

mem = Memory("agent.db", config=MemoryConfig.chatbot())           # High replay, slow decay
mem = Memory("agent.db", config=MemoryConfig.task_agent())        # Fast decay, aggressive pruning
mem = Memory("agent.db", config=MemoryConfig.personal_assistant()) # Long-term, slow core decay
mem = Memory("agent.db", config=MemoryConfig.researcher())        # Never lose anything

mem.stats() โ†’ dict

System statistics: counts, layer distribution, strength averages.

mem.downscale(factor=0.95) โ†’ dict

Manual synaptic downscaling. Usually called automatically during consolidate().

The Science

Engram is grounded in peer-reviewed cognitive science:

  • ACT-R โ€” Anderson, J.R. (2007). How Can the Human Mind Occur in the Physical Universe? Oxford University Press. ACT-R Homepage
  • Memory Chain Model โ€” Murre, J.M.J. & Chessa, A.G. (2011). One hundred years of forgetting: A quantitative description of retention. Psychonomic Bulletin & Review, 18, 592-597.
  • Ebbinghaus Forgetting Curve โ€” Ebbinghaus, H. (1885). รœber das Gedรคchtnis. Translation: Memory: A Contribution to Experimental Psychology.
  • Synaptic Homeostasis Hypothesis โ€” Tononi, G. & Cirelli, C. (2006). Sleep function and synaptic homeostasis. Sleep Medicine Reviews, 10(1), 49-62.
  • Predictive Coding โ€” Rao, R.P. & Ballard, D.H. (1999). Predictive coding in the visual cortex. Nature Neuroscience, 2(1), 79-87.
  • Dopaminergic Memory Modulation โ€” Lisman, J.E. & Grace, A.A. (2005). The hippocampal-VTA loop: controlling the entry of information into long-term memory. Neuron, 46(5), 703-713.
  • HippoRAG โ€” Yu, B. et al. (2024). HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models. NeurIPS 2024.

Storage

NeuromemoryAI uses a pluggable storage architecture. The core philosophy is zero external dependencies for the default case:

Backend Status Dependencies Use Case
SQLite + FTS5 โœ… Default None (Python stdlib) Local agents, offline use, privacy-first
Supabase ๐Ÿ”œ Planned supabase-py Multi-device sync, cloud backup
Turso/libSQL ๐Ÿ”œ Planned libsql Edge deployment, global replication
Postgres ๐Ÿ”œ Planned psycopg2 Enterprise, existing infrastructure

Default (SQLite) โ€” Works out of the box with zero config. Data stored in a local .db file. Perfect for single-agent deployments or privacy-sensitive applications.

Cloud backends โ€” Optional for users who need multi-device sync or cloud backup. Requires additional dependencies and account setup. The same Memory API works across all backends.

Roadmap

  • Core memory models (ACT-R, Memory Chain, Ebbinghaus)
  • SQLite + FTS5 persistent storage
  • Confidence scoring & reward learning
  • Synaptic downscaling & anomaly detection
  • MCP server (7 tools via FastMCP)
  • Graph-linked memories (entity relationship tracking + multi-hop search)
  • Contradiction detection & correction chains
  • Configurable parameters with agent-type presets
  • 89 tests (unit + e2e lifecycle)
  • TypeScript port (npm install neuromemory-ai)
  • PyPI publish (v0.1.1) (pip install neuromemory-ai)
  • Pluggable store backends (Supabase, Turso, Postgres)
  • Benchmarks: LoCoMo (MRR 0.255) and Temporal Dynamics (80% accuracy)
  • Consolidation summaries via LLM (compress episodic โ†’ factual)
  • Research paper: "Neuroscience-Grounded Memory for AI Agents"

TypeScript Port

A TypeScript/JavaScript port is available in the engram-ts/ directory. It provides the same neuroscience-grounded memory models with a native Node.js/Bun API.

npm install neuromemory-ai

For TypeScript-specific documentation, see engram-ts/README.md.

Testing & Edge Cases

152 tests cover unit, integration, and edge case scenarios.

# Run all tests
python -m pytest tests/ -v

# Run benchmarks
python benchmarks/run_benchmark.py --all
python benchmarks/simulate_emergence.py --days 100
python benchmarks/compare_approaches.py

For detailed edge cases, known limitations, and production recommendations, see docs/EDGE_CASES.md.

Key findings:

  • โœ… Handles Unicode, long content, SQL injection attempts
  • โœ… Scales to 10k+ memories with <500ms recall
  • โš ๏ธ SQLite concurrent writes can lock (use single instance per process)
  • โœ… Hebbian links persist with periodic co-activation

Contributing

Contributions welcome! This is an early-stage project โ€” the math is solid but the API surface is still evolving.

To contribute:

  1. Fork the repository on GitHub
  2. Clone your fork locally: git clone https://github.com/YOUR_USERNAME/engram
  3. Create a branch for your feature or fix: git checkout -b feature/my-new-feature
  4. Make your changes and add tests if applicable
  5. Run tests to ensure nothing breaks:
    python -m pytest tests/          # Python tests
    cd engram-ts && npm test         # TypeScript tests
    
  6. Commit with a clear message: git commit -m "feat: add memory pruning scheduler"
  7. Push to your fork: git push origin feature/my-new-feature
  8. Open a Pull Request on the main repository

Please ensure your code follows the existing style and includes tests for new functionality.

Citation

If you use Engram in academic work, please cite:

@software{engram2025,
  title = {Engram: Neuroscience-Grounded Memory for AI Agents},
  author = {Tang, Potato},
  year = {2025},
  url = {https://github.com/tonitangpotato/neuromemory-ai},
  note = {Open-source memory system implementing ACT-R, Memory Chain Model, and Ebbinghaus forgetting curves for AI agents}
}

Engram builds on foundational work in cognitive science:

@book{anderson2007act,
  title = {How Can the Human Mind Occur in the Physical Universe?},
  author = {Anderson, John R.},
  year = {2007},
  publisher = {Oxford University Press},
  note = {ACT-R cognitive architecture}
}

@article{murre2011forgetting,
  title = {One hundred years of forgetting: A quantitative description of retention},
  author = {Murre, Jaap M. J. and Chessa, Antonio G.},
  journal = {Psychonomic Bulletin \& Review},
  volume = {18},
  pages = {592--597},
  year = {2011},
  note = {Memory Chain Model}
}

@book{ebbinghaus1885memory,
  title = {\"Uber das Ged\"achtnis: Untersuchungen zur experimentellen Psychologie},
  author = {Ebbinghaus, Hermann},
  year = {1885},
  publisher = {Duncker \& Humblot},
  note = {Original forgetting curve research}
}

@article{tononi2006synaptic,
  title = {Sleep function and synaptic homeostasis},
  author = {Tononi, Giulio and Cirelli, Chiara},
  journal = {Sleep Medicine Reviews},
  volume = {10},
  number = {1},
  pages = {49--62},
  year = {2006},
  note = {Synaptic homeostasis hypothesis}
}

License

AGPL-3.0 โ€” open source with copyleft. Commercial license available for proprietary/SaaS use. See LICENSE-COMMERCIAL.md.


Built by an AI agent who got tired of forgetting everything between sessions.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

neuromemory_ai-0.2.0.tar.gz (115.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

neuromemory_ai-0.2.0-py3-none-any.whl (90.9 kB view details)

Uploaded Python 3

File details

Details for the file neuromemory_ai-0.2.0.tar.gz.

File metadata

  • Download URL: neuromemory_ai-0.2.0.tar.gz
  • Upload date:
  • Size: 115.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.2

File hashes

Hashes for neuromemory_ai-0.2.0.tar.gz
Algorithm Hash digest
SHA256 f343b6c6caa5f0d9685e47109d76c0bf183374b6403a12dcef2c112b52c60c4b
MD5 a29b362f0b993376b28541047b96337b
BLAKE2b-256 dce784faeced35d8330511957e5589ae8dee28f308d0efc838807ecf8dd66ef2

See more details on using hashes here.

File details

Details for the file neuromemory_ai-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: neuromemory_ai-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 90.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.2

File hashes

Hashes for neuromemory_ai-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4e13fb2c7e15b80740a3cc6247740ea48e10e1f27502fbaa727e5b3bc0a73dae
MD5 80d5b83c7873fae7c00e22fc6357b006
BLAKE2b-256 bb2d41ccd60e80d8cb3aba3550c7c341b28f29da26fb8e34d51de5bab3e93493

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page