From first install
to a useful integration.

Which version should I use?

The repository source is licensed under Apache 2.0. The published PyPI 1.3.1 artifact predates that repository license migration; its original distribution terms were not changed retroactively. See the licensing policy.

Local quickstart

This path verifies that the engine can save and retrieve a memory on your machine. It uses SQLite and the built-in deterministic hash embedder. That embedder is not semantic; this is a plumbing/evaluation path, not a semantic retrieval quality test or production configuration.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install synapse-memory-engine==1.3.1

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install synapse-memory-engine==1.3.1

export SYNAPSE_STORAGE_BACKEND=sqlite
export SYNAPSE_SQLITE_DB_PATH=./synapse_memory.db
python -m uvicorn synapse_memory.api.fastapi_server:app --host 127.0.0.1 --port 8008

$env:SYNAPSE_STORAGE_BACKEND = "sqlite"
$env:SYNAPSE_SQLITE_DB_PATH = "./synapse_memory.db"
python -m uvicorn synapse_memory.api.fastapi_server:app --host 127.0.0.1 --port 8008

from synapse_memory import SynapseClient, SynapseError

with SynapseClient(
    "http://127.0.0.1:8008",
    tenant_id="local-dev",
    timeout=10,
) as client:
    created = client.create_memory(
        "The project uses PostgreSQL in production and SQLite for local demos.",
        category="fact",
    )
    print(f"Created memory: {created.id}")

    result = client.retrieve("Which database is used for local demos?")
    print(result.fused_context or "(No context returned)")

    try:
        client.retrieve("")
    except SynapseError as exc:
        print(f"Request failed: {exc}; retryable={exc.retryable}")

python -c "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:8008/readiness').read().decode())"

Opt-in execution controls

The repository's 1.4.0 source includes SynapseRun and RunPolicy for work that an application explicitly routes through the guard. The guard can account for steps and tool calls, check a cooperative deadline, detect repeated failed calls, and record metadata-only events.

from synapse_memory.runtime import RunPolicy, SynapseRun

policy = RunPolicy(
    max_steps=30,
    max_tool_calls=20,
    timeout_seconds=120,
    max_repeated_failures=2,
)

with SynapseRun(policy=policy) as run:
    result = run.call_tool(
        "lookup_customer",
        {"customer_id": "example-id"},
        lookup_customer,
    )

Applications supply their own postconditions for tool outcomes. Synapse records whether that supplied check passed or failed; it cannot independently prove that the check represents the user's real-world objective.

Persistent run traces and retrieval evidence

The 1.4.0 source includes tenant-scoped run summaries and chronological event APIs. A run can be linked to retrieval evidence: memory IDs, ranks, allowlisted score metadata, token cost, packed/not-packed decisions, and provenance lineage.

The event contract is allowlisted and metadata-only. Raw prompts, queries, memory contents, tool arguments, and tool results are not part of the run event record. The dashboard provides a bounded inspector and redacted metadata export.

Reference: API contract · Memory provenance · Fault-injection evidence and limits.

Production-shaped deployment

The SQLite quickstart is for local evaluation only. A production-shaped deployment needs PostgreSQL with pgvector, a real semantic embedding provider, stable encryption and API secrets, protected network access, and distinct database roles.

Follow the full operations runbook, backup and recovery guide, and security policy. Helm deploys the engine and gateway; PostgreSQL is an external dependency.

Know the data boundary

Troubleshooting

Reference documentation