Synapto

Your AI agent forgets everything between sessions. Synapto fixes that.

Flat-file memory (MEMORY.md) doesn't scale — no search, no structure, no decay. Synapto gives any MCP-compatible agent a real memory: store once, recall by meaning, watch bad memories fade and good ones persist.

# remember
"Hermes uses the outbox relay pattern for Kafka"

# recall — weeks later, different session
"How does Hermes handle messaging?"
→ [stable] Hermes uses the outbox relay pattern for Kafka (score=0.94, trust=0.65)

Works with Claude Code, Cursor, Windsurf, Codex, LangGraph, Agno, or any MCP client.

Cross-agent handoffs

Pass work between Codex, Claude Code, Cursor, and other agents in plain language. Synapto stores the structured state under the hood, so the next agent can continue from a memory ID instead of a long pasted brief.

You → Codex: Plan this feature and leave a handoff for Claude to implement.
Codex → You: Handoff created for Claude: b0e1506e-d1b7-4bee-9223-4d0f8d18a1b2

You → Claude: Continue from Synapto handoff b0e1506e-d1b7-4bee-9223-4d0f8d18a1b2.
Claude → You: I read the handoff, fetched its context, and can continue.

See Cross-agent handoffs for the lifecycle, schema, and Claude/Cursor recipes.

Related MCP server: OpenChronicle

Try it in 60 seconds

Docker:

git clone https://github.com/ramonlimaramos/synapto.git && cd synapto
docker compose up -d
docker compose exec synapto synapto search "hello world"

Local:

pip install synapto
createdb synapto && psql -d synapto -c "CREATE EXTENSION vector;"
synapto init
synapto search "hello world"

What it does

Search — Ask a question, get the best memory. Behind the scenes, three signals (vector similarity, full-text, and compositional algebra) are fused into one score. You just call recall.

Graph — Entities are auto-extracted and linked. Ask "what depends on Kafka?" and get an answer via graph traversal, not keyword guessing.

Decay — Core memories live forever. Ephemeral notes fade in hours. Working context lasts about a week. Memories that get used stay alive; unused ones sink.

Trust — Mark memories as helpful or not. Bad info gets demoted 2x faster than good info gets promoted. Over time, your memory self-cleans.

Handoffs — Tell one agent to leave work for another in natural language. Synapto turns that into a structured handoff memory, and the receiver continues with get_memory, context_ids, and follow-up updates.

Quickstart

Prerequisites

• Python 3.11+

• PostgreSQL 14+ with pgvector

• Redis 7+

Install and initialize

pip install synapto
createdb synapto && psql -d synapto -c "CREATE EXTENSION vector;"
synapto init            # or: synapto init --interactive

Connect to your agent

The recommended way is uvx with --refresh — every restart pulls the latest version from PyPI, no manual upgrades:

Claude Code (~/.claude/.mcp.json):

{
  "mcpServers": {
    "synapto": {
      "command": "uvx",
      "args": ["--refresh", "synapto", "serve"],
      "env": {
        "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1"
      }
    }
  }
}

Set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 for Claude Code so Synapto remains the single memory sink instead of duplicating new memories into Claude's flat-file auto-memory.

Existing Claude Code users can upgrade their MCP config in place:

uvx --refresh synapto configure-mcp --client claude-code --yes

Restart Claude Code after running the command so the MCP subprocess receives the new environment.

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "synapto": {
      "command": "uvx",
      "args": ["--refresh", "synapto", "serve"]
    }
  }
}

Why --refresh? Without it, uvx reuses the cached environment across restarts, so a new Synapto release on PyPI will not be picked up until the cache expires or you run uv cache clean synapto manually. --refresh tells uv to re-resolve the package on every launch, adding 1–3 seconds to startup in exchange for "always on the latest version" — the right default for an alpha project that ships often. Drop the flag (or pin a version like "synapto==0.2.0") if you want to freeze the version.

Restart your agent. Synapto tools appear automatically, and any future release will be live on the next restart.

Default Memory Routing

Synapto is designed to be the primary memory sink for MCP-compatible agents. Agents should call recall before non-trivial work and call remember when users provide durable context instead of writing new memory into flat files.

subtype is optional and free-form. Recommended values include code_style, workflow, tooling, testing, security, communication, external_system, documentation, role, preference, skill, and constraint.

MCP Tools

Tool Field Limits

Synapto validates known hard limits before hitting the database, so MCP clients get actionable errors instead of raw Postgres exceptions.

CLI

synapto serve                   # start MCP server
synapto search "kafka topics"   # search from terminal
synapto doctor                  # check postgres, redis, embeddings health
synapto stats                   # memory statistics
synapto migrate status          # show applied/pending migrations
synapto export -o backup.json   # export memories
synapto import MEMORY.md --format markdown  # migrate from flat files

Depth Layers

How it works under the hood

When you call recall("kafka patterns"), Synapto runs three searches in parallel and fuses the results:

1. Vector similarity (pgvector HNSW) — finds semantically close memories

2. Full-text search (tsvector + BM25) — finds keyword matches

3. HRR compositional algebra — detects if "kafka" plays a structural role in the memory, not just appears as a word

The scores are combined via Reciprocal Rank Fusion, then weighted by decay, trust, and depth layer.

HRR (Holographic Reduced Representations) also enables queries that no vector database can do:

• probe("kafka") — find memories where Kafka is structurally involved (not just mentioned)

• reason(["kafka", "hermes"]) — find memories about both entities simultaneously (vector-space AND)

• contradict() — find memory pairs that share entities but say different things

More in docs/hrr.md.

Configuration

Config file: ~/.synapto/config.toml

[postgresql]
dsn = "postgresql://localhost/synapto"

[redis]
url = "redis://localhost:6379/0"

[embeddings]
provider = ""  # auto-select (sentence-transformers locally, openai if API key set)
model = ""
device = ""  # optional sentence-transformers device override, e.g. "cpu"

[defaults]
tenant = "default"

[decay]
ephemeral_max_age_hours = 24
purge_after_days = 30

All values can be overridden with environment variables: SYNAPTO_PG_DSN, SYNAPTO_REDIS_URL, SYNAPTO_EMBEDDING_PROVIDER, SYNAPTO_EMBEDDING_MODEL, SYNAPTO_EMBEDDING_DEVICE, SYNAPTO_DEFAULT_TENANT.

Using as a Python library

from synapto.db.postgres import PostgresClient
from synapto.db.migrations import run_migrations, ensure_hnsw_index
from synapto.embeddings.registry import get_provider
from synapto.search.hybrid import hybrid_search

pg = PostgresClient("postgresql://localhost/synapto")
await pg.connect()
await run_migrations(pg)

provider = get_provider()
await ensure_hnsw_index(pg, provider.dimension)

results = await hybrid_search(pg, provider, "outbox pattern", tenant="myproject")
for r in results:
    print(f"[{r.depth_layer}] trust={r.trust_score:.2f} {r.content}")

Documentation

Development

git clone https://github.com/ramonlimaramos/synapto.git
cd synapto
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
synapto init
pytest                          # 83 tests

License

MIT