engramai 1.0.0

Neuroscience-grounded memory system for AI agents with semantic search and auto-fallback

Engram AI 🧠

Neuroscience-grounded memory system for AI agents with semantic search and auto-fallback

What is Engram?

Engram is a production-ready memory system for AI agents, inspired by cognitive neuroscience. It provides:

• 🧠 ACT-R Activation - Memory recall based on frequency, recency, and importance
• 🔗 Hebbian Learning - Automatic association between co-activated memories
• 💤 Consolidation - Transfer memories from working → long-term storage
• 🌍 Semantic Search - Cross-language memory recall (50+ languages)
• 🔄 Auto-Fallback - Zero-config deployment with automatic provider detection

Quick Start

Installation

# Basic installation (FTS5 keyword search only)
pip install engramai

# With semantic search (recommended)
pip install "engramai[sentence-transformers]"

# With all embedding providers
pip install "engramai[all]"

Basic Usage

from engram import Memory

# Create memory system (auto-detects best embedding provider)
memory = Memory("./my-agent.db")

# Store memories
memory.add("User prefers detailed explanations", type="relational", importance=0.8)
memory.add("Project deadline: Feb 10", type="factual")

# Recall memories (semantic search)
results = memory.recall("user preferences", limit=5)
for r in results:
    print(f"{r['confidence']:.2f}: {r['content']}")

# Run consolidation (strengthens important memories)
memory.consolidate(days=1.0)

MCP Server (for OpenClaw, BotCore, etc.)

# Set database path
export ENGRAM_DB_PATH=./my-agent.db

# Start MCP server (auto-detects embedding provider)
python3 -m engram.mcp_server

# Or configure specific provider
export ENGRAM_EMBEDDING=sentence-transformers  # or ollama, openai, none, auto
python3 -m engram.mcp_server

Features

🎯 Zero-Config Deployment

Engram automatically detects and uses the best available embedding provider:

1. Ollama (if running locally with embedding models)
2. Sentence Transformers (if installed)
3. OpenAI (if API key configured)
4. FTS5 (always available as fallback)

# Just install and go - no configuration needed!
pip install "engramai[sentence-transformers]"
python3 -m engram.mcp_server

🌍 Cross-Language Semantic Search

Find memories across languages with zero additional configuration:

memory.add("marketing是个大难题")  # Chinese

# Query in English - finds the Chinese memory!
results = memory.recall("marketing is difficult")
# ✅ Returns: "marketing是个大难题"

Supports 50+ languages including:

• English, Chinese, Spanish, French, German, Russian
• Japanese, Korean, Arabic, Hindi
• And many more...

🔬 Neuroscience-Grounded

Based on cognitive science models:

• ACT-R - Activation from frequency, recency, spreading activation
• Hebbian Learning - "Neurons that fire together, wire together"
• Memory Consolidation - Simulates sleep-based memory strengthening
• Forgetting Curve - Natural decay based on Ebbinghaus' research

📊 Session-Aware Working Memory

Reduces API calls by 70-80% for continuous conversations:

# First query - full retrieval
results = memory.session_recall("user preferences", session_id="chat_123")

# Follow-up query on same topic - uses cached working memory!
results = memory.session_recall("what does user like?", session_id="chat_123")
# ⚡ No database query - instant response

Configuration

Environment Variables

Variable	Values	Description
ENGRAM_EMBEDDING	auto (default), sentence-transformers, ollama, openai, none	Embedding provider
ENGRAM_ST_MODEL	Model name (default: paraphrase-multilingual-MiniLM-L12-v2)	Sentence Transformers model
ENGRAM_OLLAMA_MODEL	Model name (default: nomic-embed-text)	Ollama embedding model
OPENAI_API_KEY	API key	Required for OpenAI embeddings
ENGRAM_DB_PATH	File path	Database location (for MCP server)

Provider Comparison

Provider	Pros	Cons	Use When
Auto ⭐ (default)	Zero config, adapts to environment	Non-deterministic selection	Production, distribution
Sentence Transformers	Free, offline, 50+ languages	~118MB model download	Privacy-sensitive, no API costs
Ollama	Free, offline, customizable	Requires Ollama running	You already use Ollama
OpenAI	Highest quality	Costs API credits, needs internet	Prototyping, cloud-only
None (FTS5)	No dependencies, instant	Keyword-only, no semantic search	Testing, minimal setups

Examples

Store Different Memory Types

# Factual knowledge
memory.add("Paris is the capital of France", type="factual")

# Personal relationships
memory.add("User likes detailed technical explanations", type="relational", importance=0.9)

# Procedural knowledge (how-to)
memory.add("To deploy: git push origin main", type="procedural", importance=0.8)

# Episodic memories (events)
memory.add("Shipped feature X on Jan 15", type="episodic")

Recall with Filters

# Only relational memories
results = memory.recall("user preferences", types=["relational"], limit=3)

# High-confidence only
results = memory.recall("deadlines", min_confidence=0.7)

# Context-aware (spreading activation)
results = memory.recall("project status", context=["planning", "timeline"])

Memory Consolidation

# Simulate one day of sleep (strengthens important memories)
memory.consolidate(days=1.0)

# Prune weak memories below threshold
memory.forget(threshold=0.01)

# Apply reward/punishment
memory.reward("Great job!", recent_n=3)  # Strengthens last 3 memories

Export/Import

# Export to file
memory.export("backup.db")

# Import from file (Python API)
from shutil import copyfile
copyfile("backup.db", "./my-agent.db")
memory = Memory("./my-agent.db")

Architecture

User Query
    ↓
Vector Search (semantic)
    ↓
FTS5 Search (lexical)
    ↓
Merge & Dedupe
    ↓
ACT-R Activation (cognitive dynamics)
    ↓
Confidence Scoring (metacognition)
    ↓
Ranked Results

Development

# Clone repository
git clone https://github.com/tonitangpotato/engramai.git
cd engramai

# Install in development mode
pip install -e ".[dev,all]"

# Run tests
pytest

# Run provider detection test
python3 engram/provider_detection.py

Integration

With OpenClaw

Engram is the default memory system for OpenClaw agents.

With BotCore

import { createBot } from 'botcore';

const bot = await createBot({ workspace: './my-bot' });
await bot.memory.store('Important context', { type: 'factual' });
const results = await bot.memory.recall('context');

Standalone Python

from engram import Memory

memory = Memory("./agent.db")
memory.add("Remember this", importance=0.8)
results = memory.recall("what to remember?")

MCP Protocol

Any MCP-compatible client can use Engram:

{
  "mcpServers": {
    "engram": {
      "command": "python3",
      "args": ["-m", "engram.mcp_server"],
      "env": {
        "ENGRAM_DB_PATH": "./my-agent.db"
      }
    }
  }
}

Performance

Metric	Value	Notes
Model size	118MB	One-time download (Sentence Transformers)
Startup time	~200ms	After first download
Vector generation	~250 mem/sec	CPU (M2 chip)
Search latency	10-50ms	1000 memories
Cross-language accuracy	100%	Test cases: 3/3 ✅

Documentation

• Embedding Configuration Guide
• Phase 1-2 Summary
• Phase 3 Complete Report
• API Documentation

Credits

Engram is inspired by:

• ACT-R (Adaptive Control of Thought-Rational) - Carnegie Mellon
• Hebbian Learning - Donald Hebb
• Memory Consolidation - Sleep research by Walker, Stickgold
• Forgetting Curve - Hermann Ebbinghaus

License

MIT License - see LICENSE for details.

Support

• Issues: https://github.com/tonitangpotato/engramai/issues
• Discussions: https://github.com/tonitangpotato/engramai/discussions
• OpenClaw Discord: https://discord.com/invite/clawd