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:

| ❌ Flat text | ❌ Cloud-locked | ❌ All-or-nothing | |---|---|---| | No relationships. No temporal awareness. Just a growing blob of text. | Your conversations live on someone else's server. Your data, their infrastructure. | Every memory has equal weight. Nothing is forgotten. The context window drowns. |

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:
SYNAPSEFALKORDBHOST=localhost
SYNAPSELLMAPI_KEY=your-key
SYNAPSELLMBASE_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

| Algorithm | What It Does | Biological Analog | |-----------|-------------|-------------------| | Salience Scoring | Scores entities 0.0–1.0 by recency, frequency, corrections, and emotional markers | Amygdala tagging important experiences | | Forgetting Curve | Ebbinghaus exponential decay — important memories decay 4x slower | Memory consolidation during sleep | | Consolidation Engine | Hebbian strengthening of co-occurring entities + contradiction detection + pruning | Sleep replay and synaptic pruning |

Advanced Cognitive Functions

| Algorithm | What It Does | Biological Analog | |-----------|-------------|-------------------| | Pattern Completion | Given a partial cue, retrieves the full context subgraph via BFS expansion | CA3 autoassociative memory | | Reconsolidation | Recalled memories enter a labile window — new info gets priority encoding (spaced repetition) | Memory reactivation lability | | Prediction Error | Novelty detection + contradiction-triggered updates + surprise signals for unexpected contexts | Hippocampal surprise signal | | Schema Extraction | Periodically clusters entities into generalized "schema nodes" — the slow learning system | Neocortex (Complementary Learning Systems) | | Pattern Separation | Entity fingerprints + Jaccard similarity to prevent context contamination between similar conversations | Dentate gyrus | | Cognitive Map | Semantic path finding, entity neighborhoods, topic clustering — navigates the graph like a spatial map | Grid cells + place cells |

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  │  │ syncturn  │  │ synapseremember   │  │
│  │ (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

| Tool | Purpose | Example | |------|---------|---------| | synapsequery | Search memories. Set attime for point-in-time queries. | "What database were we using before the switch?" | | synapse_remember | Save a durable fact permanently. Never decays. | "User prefers concise responses" |

Two Usage Modes

🧠 Brain Mode (Synapse only)

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

memory:
  memory_enabled: false
  userprofileenabled: 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
  userprofileenabled: 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.

| Metric | Naive Implementation | Synapse (Optimized) | Improvement | |--------|-----------------------|-----------------------|-------------| | Cost per 100 turns | $0.0705 | $0.0192 | 73% reduction | | Prefetch latency | 0.70s (blocking) | 0.01s (cached) | 70x faster | | LLM calls per 100 turns | 200 | 14 | 86% fewer | | Prompt overhead per turn | 232 tokens | 91 tokens | 61% less | | Blocking time per 100 turns | 70s | ~0s | eliminated |

Supported LLM Providers

Any OpenAI-compatible endpoint works:

| Provider | Base URL | Free? | Embeddings? | |----------|----------|-------|-------------| | Ollama (local) | http://localhost:11434/v1 | ✅ | ✅ | | OpenRouter | https://openrouter.ai/api/v1 | — | ✅ | | OpenAI | https://api.openai.com/v1 | — | ✅ | | vLLM | http://localhost:8000/v1 | ✅ | ✅ | | LM Studio | http://localhost:1234/v1 | ✅ | ✅ | | DeepSeek | https://api.deepseek.com | — | — | | Together | https://api.together.xyz/v1 | — | — | | Z.AI / GLM | https://open.bigmodel.cn/api/paas/v4 | — | — |

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

| Variable | Default | Description | |----------|---------|-------------| | SYNAPSEFALKORDBHOST | localhost | FalkorDB host | | SYNAPSEFALKORDBPORT | 6379 | FalkorDB port | | SYNAPSELLMAPI_KEY | (required) | LLM API key | | SYNAPSELLMBASE_URL | (required) | LLM base URL | | SYNAPSELLMMODEL | gpt-4o-mini | Model for entity extraction | | SYNAPSEEMBEDDINGMODEL | text-embedding-3-small | Embedding model | | SYNAPSEBATCHSIZE | 5 | Turns per episode | | SYNAPSEHALFLIFE_DAYS | 7.0 | Forgetting curve half-life |

Tuning Guide

| Use Case | Half-Life | Batch Size | |----------|-----------|------------| | Coding assistant | 3–7 days | 5 | | Research assistant | 14–30 days | 5 | | Personal assistant | 30–90 days | 3 | | General purpose | 7 days | 5 |

Documentation

| Document | What's Inside | |----------|---------------| | User Guide | Installation, quick start, tools reference, troubleshooting, FAQ | | Architecture | System design, data flow, optimization details | | Configuration | All env vars, LLM providers, tuning guide | | Hippocampus Layer | Algorithm formulas, biological references | | Benchmarks | Performance methodology, calculations, assumptions |

Contributing

We welcome contributions! See CONTRIBUTING.md for the full guide.

git clone https://github.com/ardhaecosystem/synapse.git
cd synapse
pip install -e ".[dev]"
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               synapsequery + synapseremember
├── 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

License

MIT © Ardha Studios