Self-hosted temporal memory for AI agents.
If this project is useful to you, consider ⭐ starring the repo — it helps others discover it.

The Problem

Every AI agent memory system today falls into one of three buckets:

The Solution

Synapse gives AI agents a biologically-inspired memory system — a temporal knowledge graph with a hippocampus layer that scores importance, manages forgetting, and consolidates memories during idle time. Just like a real brain.

• 🕐 Temporal — Knows when facts were true, not just that they were true. Query the past, not just the present.
• 🔒 Self-hosted — Your conversations stay on your machine. FalkorDB in Docker. Zero cloud dependency.
• 🧠 Biological — Important memories persist. Unimportant ones fade. Mistakes are remembered vividly. Just like you.
• 🔌 Provider-agnostic — Works with any OpenAI-compatible LLM. OpenRouter, Ollama, vLLM, OpenAI — your choice.
• ⚡ Optimized — Projected 73% cheaper, 70x faster prefetch, 86% fewer LLM calls than naive implementations. Zero blocking latency. (See methodology)

Built on Graphiti + FalkorDB. Ships as a Hermes Agent memory provider plugin — drops in with zero core changes.

Quick Start

Three commands. That's it.

# 1. Start FalkorDB (self-hosted, privacy-first)
docker run -d --name falkordb -p 6379:6379 falkordb/falkordb:latest

# 2. Install Synapse
pip install "git+https://github.com/ardhaecosystem/synapse.git"

# 3. Configure Hermes
hermes config set memory.provider synapse
# Add to ~/.hermes/.env:
# SYNAPSE_FALKORDB_HOST=localhost
# SYNAPSE_LLM_API_KEY=your-key
# SYNAPSE_LLM_BASE_URL=https://openrouter.ai/api/v1

Your agent now has a memory that:

• ✅ Remembers every conversation and extracts entities automatically
• ✅ Knows when facts changed and can answer "what was true on June 20?"
• ✅ Scores memory importance and forgets what doesn't matter
• ✅ Consolidates memories in the background like sleep replay
• ✅ Lets the agent explicitly save facts worth remembering forever

The Hippocampus Layer

This is the novel contribution. Nine algorithms inspired by biological memory — the part that makes Synapse a brain, not a database.

Core Memory Management

Advanced Cognitive Functions

How It Works

┌──────────────────────────────────────────────────────────┐
│                      Hermes Agent                          │
│                                                           │
│  System Prompt (frozen per session):                      │
│  ┌─────���───────────────────────────────────────────────┐  │
│  │ "You remember your user prefers concise responses.  │  │
│  │  They work on AI projects using Python and Docker." │  │
│  │  (pulled from the graph, not from a static file)     │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  Every turn:                                              │
│  ┌───────────┐  ┌────────────┐  ┌─────────────────────┐  │
│  │  prefetch  │  │ sync_turn  │  │ synapse_remember   │  │
│  │ (BM25 +    │  │ (batch +   │  │ (explicit write →  │  │
│  │  pattern   │  │  prediction│  │  max salience,     │  │
│  │  completion)│ │  error +   │  │  never decays)     │  │
│  │            │  │  reconsol.)│  │                    │  │
│  └───────────┘  └────────────┘  └────────────────────��┘  │
│                                                           │
│  Background ("sleep"):                                    │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ Schema Extraction → "User works on AI projects"      │  │
│  │ Forgetting Curve → prunes forgotten memories         │  │
│  │ Consolidation → strengthens important connections   │  │
│  └─────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
                    │
                    ▼
            ┌───────────────┐
            │   FalkorDB    │
            │ (self-hosted  │
            │  in Docker)   │
            └───────────────┘

Tools Available to the Agent

Two Usage Modes

🧠 Brain Mode (Synapse only)

Disable native MEMORY.md/USER.md, use Synapse as the sole memory system:

memory:
  memory_enabled: false
  user_profile_enabled: false
  provider: synapse

The agent gets:

• Full system prompt with user profile + environment facts pulled from the graph
• synapse_remember as the explicit memory tool (replaces the native memory tool)
• Automatic brain-mode instructions in the system prompt

🔗 Supplementary Mode (Native + Synapse)

Keep native memory, add Synapse for temporal graph memory:

memory:
  memory_enabled: true
  user_profile_enabled: true
  provider: synapse

The agent gets:

• Native MEMORY.md/USER.md as normal
• Synapse adds temporal knowledge graph memory on top
• Native writes are mirrored to the graph automatically
• System prompt is minimal (native handles injection)

Performance

Projected estimates based on architectural analysis. See the benchmark methodology for calculations, assumptions, and reproduction steps.

Supported LLM Providers

Any OpenAI-compatible endpoint works:

💡 Want 100% free + private? Use Ollama locally for both LLM and embeddings. Zero data leaves your machine.

Configuration

All configuration via environment variables with the SYNAPSE_ prefix:

Tuning Guide

Documentation

Start FalkorDB for testing

docker run -d --name falkordb -p 6379:6379 falkordb/falkordb:latest

Run tests

pytest tests/ -v

Lint

ruff check src/ tests/

We use **TDD** (test-first), **conventional commits**, and **PR-based workflow** — every change goes through CI with FalkorDB as a service container.

### Project Structure

src/synapse/ ├── config.py Configuration ├── falkor.py FalkorDB helper + temporal workaround ├── encoding.py Batch turn buffering ├── retrieval.py BM25 prefetch + background cache ├── tools.py synapse_query + synapse_remember ├── provider.py MemoryProvider implementation └── hippocampus/ ├── salience.py Salience scoring (4-factor) ├── forgetting.py Ebbinghaus decay curve ├── consolidation.py Hebbian + contradiction detection ├── pattern_completion.py CA3 BFS subgraph expansion ├── reconsolidation.py Recall tracking + activation window ├── prediction_error.py Novelty + contradiction + surprise ├── schema_extraction.py Neocortex — CLS slow learning ├── pattern_separation.py DG — Jaccard fingerprint comparison └── cognitive_map.py Grid/place cells — graph navigation

---

## Biological References

The hippocampus layer is grounded in neuroscience research:

| Algorithm | Key Reference |
|-----------|---------------|
| Complementary Learning Systems | McClelland et al. (1995) |
| Reconsolidation | Nader et al. (2000) |
| Pattern Separation | Leutgeb et al. (2007) |
| Prediction Error | Kumaran & Maguire (2006) |
| CA3 Autoassociative Memory | Rolls (2015) |
| Cognitive Maps | O'Keefe & Nadel (1978) |
| Hippocampal Replay | Wilson & McNaughton (1994) |

---

## Roadmap

- [x] Core memory provider (Graphiti + FalkorDB)
- [x] 9 hippocampus algorithms
- [x] `synapse_remember` explicit memory tool
- [x] Brain-aware system prompt (native memory detection)
- [x] BM25-only optimized prefetch
- [x] Batch episode ingestion
- [ ] CLI commands (`hermes synapse status/consolidate/export`)
- [ ] Leiden community detection for schema extraction
- [ ] LLM-powered schema summaries
- [ ] Graph visualization dashboard
- [ ] Multi-agent shared memory via FalkorDB replication

---