synapto 0.3.0

Persistent memory graph for AI coding agents — semantic search, knowledge graph, and time-based decay over MCP

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.

What you say	What Synapto does
"Codex, leave this for Claude."	Stores a project memory with metadata.kind = "agent_handoff".
"Claude, continue from this handoff ID."	Fetches the full memory with get_memory and verifies the metadata.
"Any handoffs for me?"	Uses recall to find ranked candidates, then fetches the relevant packet.
"Mark it ready for review."	Appends a follow-up memory with the same task_id.

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

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"]
    }
  }
}

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.

MCP Tools

Tool	What it does
remember	Store a memory (entities and search vectors are created automatically)
recall	Search memories by meaning
get_memory	Fetch the complete content and metadata for one recalled memory
get_memories	Fetch complete content for multiple recalled memories
relate	Link two entities ("Hermes" --[produces]--> "agent.messages")
forget	Soft-delete a memory
trust_feedback	Mark a memory as helpful or unhelpful
find_contradictions	Find memory pairs that disagree
graph_query	Walk the knowledge graph (N-hop)
list_entities	Browse known entities
memory_stats	View counts and distribution
maintain	Run decay and cleanup

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

Layer	Half-life	Example
core	Forever	"Our API uses REST, never GraphQL"
stable	~6 months	"Auth service is in Go, everything else is Python"
working	~1 week	"Currently refactoring the payment module"
ephemeral	~6 hours	"Debugging: the timeout was 30s, changed to 60s"

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 on CPU, openai if API key set)
model = ""

[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_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

HRR deep dive	Compositional algebra, probe, reason, contradict
Trust scoring	Feedback loop and contradiction workflow
Cross-agent handoffs	Coordinate planning, implementation, and review across agents
Migrations	Versioned SQL files with rollback
Claude Code	Setup and usage with Claude Code
Cursor	Setup and usage with Cursor
LangGraph	Using Synapto as a LangGraph tool
Agno	Using Synapto with Agno agents

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