SynaptiQ Core

Give AI applications memory they can retrieve, inspect, and update.

SynaptiQ stores facts and relationships in PostgreSQL, organizes them by tenant and project context, and retrieves relevant memory through a FastAPI service and MCP tools. Use it as the memory layer behind an assistant, agent, or application.

Quick start · Try it · Architecture · API · GCP hosting · Contributing

Why SynaptiQ?

A conversation contains useful details that should outlive a single session: project goals, changing priorities, relationships, and preferences. Replaying an entire transcript makes the application responsible for finding the relevant parts and deciding which facts still apply.

SynaptiQ gives those details an explicit structure and lifecycle. An application can save a fact, associate it with a project, retrieve it later, and update or supersede it when the situation changes. The application or model still decides what to remember and how to use the returned context; SynaptiQ does not train the model or automatically capture every conversation.

For example: store “Example app → goal → Ship the local prototype” under work.projects.example. In a later session, ask for context about that project. The stored goal can become part of the assistant's next prompt.

Related MCP server: MCP AI Memory

What makes the approach different?

These are architectural distinctions, not competitive benchmarks. Other systems can implement similar behavior; SynaptiQ packages these choices together.

Use it when your application needs evolving, structured memory across sessions. For a short-lived chat or a document-only search feature, a smaller solution may be sufficient. SynaptiQ is a memory backend, not an agent runner or a chat UI.

How it works

1. Store: submit a fact or relationship with a tenant and context_anchor. The write path normalizes entities and predicates and checks for duplicates.

2. Persist: PostgreSQL holds canonical facts, lifecycle information, and supporting evidence. Memory survives API restarts while the database persists.

3. Resolve: a later request retrieves context using query, scope, intent, lifecycle, and ranking rules. Optional embeddings add a semantic signal.

4. Maintain: update, supersede, or delete facts as their meaning changes. Separate worker processes support enrichment and maintenance when configured.

Read the architecture guide for the write/read paths, trust boundaries, design tradeoffs, and a map from each component to its code.

Quick start

Prerequisites: Python 3.12, Docker with Compose, and a free local port 5432. Run these commands from the repository root. The basic setup requires no model API key and does not enable cloud services or the embedding pipeline.

1. Install and start PostgreSQL

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --require-hashes -r requirements.txt
cp .env.example .env
docker compose up -d postgres
until docker compose exec -T postgres pg_isready -U cme -d cme; do sleep 1; done

2. Initialize a fresh database and start the API

bash -e -c 'for f in migrations/*.sql; do
  docker compose exec -T postgres psql -U cme -d cme -v ON_ERROR_STOP=1 < "$f"
done'
uvicorn api.main:app --host 127.0.0.1 --port 8080 --reload

The migration loop stops on a failed migration. For an existing database, back up first and inspect the tracked runner with python scripts/stabilization/run_schema_migrations.py --help; do not replay the fresh-database loop. See the database guide.

3. Check readiness

In another terminal:

curl --fail-with-body http://127.0.0.1:8080/healthz
curl --fail-with-body http://127.0.0.1:8080/readyz

Open the interactive API docs. /healthz checks liveness; /readyz checks database readiness. Docker Compose runs PostgreSQL; the command above runs the API on your host. The database uses example local credentials, and both services bind to localhost. Local API defaults permit unauthenticated requests.

Store and retrieve your first memory

Save a project goal:

curl --fail-with-body http://127.0.0.1:8080/mcp/invoke \
  -H 'Content-Type: application/json' \
  -d '{"tool_name":"memory_store_fact","args":{"tenant_id":"local-example","context_anchor":"work.projects.example","payload":{"subject":"Example app","predicate":"goal","object_value":"Ship the local prototype"}}}'

Retrieve context about that project:

curl --fail-with-body http://127.0.0.1:8080/mcp/invoke \
  -H 'Content-Type: application/json' \
  -d '{"tool_name":"memory_resolve_context","args":{"tenant_id":"local-example","context_anchor":"work.projects.example","user_message":"What is the goal of Example app?","limit":5}}'

Inspect the JSON response for the stored goal and its identifiers. Save returned fact IDs when you need to update or delete a specific record. These examples are local development requests; authenticated installations also require a bearer token and must obey the tenant associated with the authenticated identity.

Use the MCP write tools for persistence. The old REST write routes /memory/attributes and /memory/relationships return HTTP 410.

Connect an MCP client

The HTTP MCP endpoint is http://127.0.0.1:8080/mcp. For clients accepting this configuration shape:

{
  "mcpServers": {
    "synaptiq": {"url": "http://127.0.0.1:8080/mcp"}
  }
}

Use your client's HTTP MCP configuration format and discover the server's tools. Useful entry points include memory_capabilities, memory_store_fact, memory_store_facts, and memory_resolve_context. The convenience endpoint /mcp/invoke above accepts JSON directly; protocol clients use /mcp.

Remote clients need a reachable, authenticated endpoint—their localhost is not your computer. Configuration, OAuth support, and approval flows vary by client. This package does not claim end-to-end certification for individual Claude or Codex clients. See the API reference.

Local core and optional features

A context anchor organizes memory; it is not an authorization boundary. A shared API token does not give each caller a separate tenant identity. See the architecture security boundaries.

Hosting and configuration

Start with .env.example. Keep actual secrets in your own .env or secret manager. Non-local environments require configured authentication; set ENV=production, choose the supported authentication method, and restrict CORS_ALLOWED_ORIGINS to your client origins. Admin operations use a separate token.

The GCP hosting guide covers Cloud Run, PostgreSQL/pgvector, Secret Manager, migrations, and optional workers using portable examples. The Dockerfile builds the API image. The source package contains no website, hosted service, private cloud configuration, or deployment workflows.

Repository map

Troubleshooting

Develop and verify

python -m pip install --require-hashes -r requirements-dev.txt
python -m pytest -q
ruff check .
pip-audit -r requirements-dev.txt --disable-pip --no-deps

The prepared core passed 320 tests, and a container smoke check covered fresh migrations, API startup, MCP tool discovery, and a real database save/search. Many tests use mocks. These checks do not establish production capacity, a live GCP deployment, or compatibility with every MCP client. No performance benchmark or availability guarantee is claimed.

See CONTRIBUTING.md for development and SECURITY.md for security reporting. The publication scope explains the included source boundaries.

License

MIT. Third-party packages retain their own licenses.