openchronicle-mcp server

OpenChronicle

<!-- markdownlint-disable MD033 --> <!-- fleet-confidence --> · claude-fable-5 · 2026-08-30 · details <!-- /fleet-confidence --> <!-- markdownlint-enable MD033 -->

A memory database for LLM agents. Persistent semantic + keyword memory, project namespacing, git-onboard, served over HTTP REST and MCP from a single ASGI process. Runs on your hardware.

What it does

and rejected approaches that survive context compression and new conversations. Retrieve them with hybrid full-text and semantic search via Reciprocal Rank Fusion.

• Persistent memory across sessions. Save decisions, milestones,

for one workstream doesn't leak into another.

• Project namespacing. Memory is scoped to projects, so context

return summaries ready for memory ingestion. Seeds long-term memory with the WHY behind existing code.

• Git onboarding. Clone a repo, cluster commits by relatedness,

(/api/v1/*) and the MCP streamable-HTTP transport (/mcp) on the same port. Single container, single port mapping, single healthcheck.

• One process, two transports. FastAPI hosts both the REST surface

down, search degrades cleanly to FTS5-only and surfaces the degraded state via /api/v1/health and the MCP health tool. Backfill catches up when the provider returns; the static /health endpoint remains a minimal liveness probe.

• Embedding-failure degradation. When the embedding provider goes

builds include the bounded Prometheus recorder and guarded /metrics endpoint; the released v3.3.0 image does not. Release and enabled collection remain subject to the performance gates. Eligible builds opt in with OCMETRICSENABLED=true; the default stays off. See the metrics configuration and the optional local monitoring runbook.

• Optional operational metrics (unreleased). Development and benchmark

savepoint atomicity. Re-runs are idempotent. Future schema changes drop in as NNN_.sql files.

• Schema migration framework. Versioned .sql migrations with

Backup-before-destructive policy: vacuum runs a backup first as part of the same job. Integrity-check failures trigger emergency backups.

• Atomic online backups. Uses SQLite's online backup API.

What it isn't

Open WebUI, etc. via the MCP server.

• Not a conversation engine. v3 has no LLM. Use Claude Code, Goose,

is supported but optional — disabled by default for trusted-LAN deployments. See docs/configuration/security_posture.md for the when-to-enable guidance.

• Not multi-tenant. Single user. Bearer-token auth via OCAPIKEY

to a directory next to it. Cross-device sync isn't built in; a backup-only Dropbox design is documented but not implemented in docs/design/0001-cloud-backup.md.

• Not a cloud sync layer. The DB lives on your hardware. Backups go

By design.

Install

From source:

pip install -e ".[mcp,openai]"
oc init
oc serve

The default oc serve binds 127.0.0.1:8000. Override with --host/--port or OCAPIHOST/OCAPIPORT.

Docker (single container, NAS-friendly):

docker run --rm \
  -p 8000:8000 \
  -e OC_API_HOST=0.0.0.0 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config \
  ghcr.io/carldog/openchronicle-mcp:latest

Shortened. The full README is on GitHub.