engramai 1.0.0
Neuroscience-grounded memory system for AI agents with semantic search and auto-fallback
License: MIT
Requires Python: >=3.9
Keywords: ai, memory, agent, cognitive, neuroscience, semantic-search

# Engram AI 🧠

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

[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9+-blue)](https://www.python.org/)

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

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

```python
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.)

```bash
# 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)

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

```python
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:

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

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

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

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

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

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

```typescript
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

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

```json
{
  "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](engram/EMBEDDING-CONFIG.md)
- [Phase 1-2 Summary](PHASE1-2-SUMMARY.md)
- [Phase 3 Complete Report](PHASE3-COMPLETE.md)
- [API Documentation](docs/API.md)

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