Synaptra

A biologically-inspired synaptra memory system for AI agents, exposed as an MCP server. Gives agents persistent memory with human-like properties: memories decay over time, strengthen with use, form relationships, and consolidate automatically.

Features

• Four memory types with different decay rates — working (hours), episodic (days), semantic (weeks), procedural (months)

• FSRS-inspired decay — retrievability computed on-the-fly: R(t) = e^(-t / 9S)

• Multi-strategy retrieval — semantic search (HNSW cosine), BM25 keyword search, temporal recency, and graph traversal fused with Reciprocal Rank Fusion (RRF)

• Spreading activation — retrieving a memory strengthens its neighbors in the relationship graph

• Automatic linking — new memories are linked to similar existing ones via cosine similarity

• Contradiction detection — flags semantically similar memories with negation signals

• Consolidation pipeline — promotes working->episodic->semantic/procedural, archives forgotten memories, merges near-duplicates

• Version history — every update creates a snapshot for full audit trail

• CLI tool — browse, search, and manage memories from the terminal

• Windows service — runs as a background service via Task Scheduler (no admin required)

Related MCP server: Mnemotree

Installation

Requires Python 3.11+.

pip install synaptra

This installs the MCP server, CLI tool, and all dependencies including sentence-transformers (all-MiniLM-L6-v2, 384d) and SurrealDB (embedded).

Quick Start

1. Start the server

synaptra

This starts the Streamable HTTP MCP server on http://127.0.0.1:8050/mcp.

2. Connect from Claude Code

Add to your Claude Code MCP config (~/.claude.json or project .mcp.json):

{
  "mcpServers": {
    "synaptra": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8050/mcp"]
    }
  }
}

3. Use the CLI

# Search memories
synaptra-cli recall "python programming"

# Browse
synaptra-cli list
synaptra-cli list --type semantic --tags "project,design"

# Get full details
synaptra-cli get <memory-id>

# Store a memory
synaptra-cli store "Python's GIL was removed in 3.13" --type semantic --tags "python,news"

# Pipe from stdin
echo "meeting notes here" | synaptra-cli store -

# System health
synaptra-cli stats
synaptra-cli consolidate --dry-run

# JSON output for scripting
synaptra-cli --json list | jq '.data.memories[].content'

Run synaptra-cli --help for all commands and flags.

Windows Service

Run the server as a background service that auto-starts at logon:

synaptra-service install    # Register with Task Scheduler
synaptra-service start      # Start now
synaptra-service status     # Check health
synaptra-service stop       # Stop
synaptra-service remove     # Uninstall
synaptra-service debug      # Run in foreground (development)

No admin elevation or pywin32 required. Uses Task Scheduler with auto-restart on failure (3 attempts, 1 minute apart).

Environment Variables

MCP Tools (14)

Architecture

cognitive_memory/
  server.py          Streamable HTTP MCP server (FastMCP + uvicorn)
  cli.py             CLI tool (click, connects via MCP client)
  service.py         Windows Task Scheduler service management
  engine.py          Central orchestrator
  surreal_storage.py SurrealDB embedded storage (HNSW vectors, BM25 FTS, graph edges)
  embeddings.py      Sentence-transformers embedding service
  retrieval.py       Two-phase RRF pipeline with spreading activation
  decay.py           FSRS-inspired decay engine (pure functions)
  consolidation.py   Promotion, archival, clustering, merging
  classification.py  Heuristic type classification + importance scoring
  config.py          YAML defaults + DB overrides
  models.py          Pydantic domain models
  protocols.py       Storage protocol (typing.Protocol)
  schema.surql       SurrealDB schema definition

Configuration

All config uses dot-notation keys. View/set at runtime via memory_config tool or synaptra-cli config.

Key settings:

Backup & Restore

CM provides a full backup/restore system via the cm backup subgroup. Backups are logical NDJSON exports — backend-agnostic and inspectable without unpacking.

Quick reference

# Create a backup (stops CM, exports, restarts CM)
cm backup create

# Verify a backup artifact (light check)
cm backup verify ~/.synaptra/backups/cm-20260515T040000Z

# Deep verify (loads into temp DB, runs HNSW query, ~30 s)
cm backup verify --deep ~/.synaptra/backups/cm-20260515T040000Z

# Restore into a fresh directory
cm backup restore ~/.synaptra/backups/cm-20260515T040000Z

# Restore into a specific target
cm backup restore ~/.synaptra/backups/cm-20260515T040000Z --target ~/myrestore

Stop-CM ritual

Backups require exclusive access to the SurrealKV data directory. cm backup create automatically:

1. Stops the CognitiveMemory Windows scheduled task.

2. Waits for the SurrealKV file lock to release (~5 s).

3. Opens SurrealKV directly and streams all data to NDJSON.

4. Restarts the CM service.

5. CM cold-start (SurrealKV clog replay) takes ~2 minutes — expected behavior.

The ~2 min downtime is accepted. Backups run during /dream (a maintenance window) or on explicit operator demand.

Backup artifact layout

~/.synaptra/backups/cm-<timestamp>Z/
  manifest.json          # Metadata: counts, schema hash, version, timing
  schema.surql           # Snapshot of CM schema at backup time
  memory.ndjson          # All memory records (15 fields each, incl. embedding)
  memory_version.ndjson  # Edit history
  consolidation_log.ndjson
  preference.ndjson
  edges/
    causes.ndjson        # One file per relationship type
    follows.ndjson
    contradicts.ndjson
    supports.ndjson
    relates_to.ndjson
    supersedes.ndjson
    part_of.ndjson
    describes.ndjson

Each file is line-delimited JSON — head memory.ndjson | python -m json.tool works without unpacking anything.

Rollback procedure

Use scripts/cm-rollback.ps1 for a full rollback to a previous backup:

# Usage: cm-rollback.ps1 <backup_dir>
.\scripts\cm-rollback.ps1 "$env:USERPROFILE\.synaptra\backups\cm-20260515T040000Z"

The script uses atomic rename — live data is never directly overwritten. If restore fails mid-way, CM restarts against the untouched live data. The old live data is moved to data.pre-rollback-<ts> as a safety net (pruned after 7 days).

Retention policy

The retention pruner runs automatically after cm backup create. Policy:

Pre-rollback safety copies (data.pre-rollback-<ts>) are pruned after 7 days.

Worst-case storage: 17 backups × ~10 MB ≈ 170 MB.

Pre-dream integration

The /dream skill runs cm backup create + cm backup verify --deep as its first step before any memory reshaping. If either fails, dream aborts. This ensures every consolidation pass has a verified rollback point.

Stale backup warning

The memory_health MCP tool exposes:

• most_recent_backup_age_days: days since the most recent backup (None if none exist).

• backup_is_stale: true if age > 7 days or no backups exist.

The session-start skill surfaces backup_is_stale as a visible warning.

Development

pip install synaptra[dev]
pytest

License

MIT