openchronicle-mcp

OpenChronicle

[code confidence] _{· claude-fable-5 · 2026-08-30 · details}

[License: AGPL-3.0] [Docker] [Python 3.14+]

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

• Persistent memory across sessions. Save decisions, milestones, and rejected approaches that survive context compression and new conversations. Retrieve them with hybrid full-text and semantic search via Reciprocal Rank Fusion.
• Project namespacing. Memory is scoped to projects, so context for one workstream doesn't leak into another.
• Git onboarding. Clone a repo, cluster commits by relatedness, return summaries ready for memory ingestion. Seeds long-term memory with the WHY behind existing code.
• One process, two transports. FastAPI hosts both the REST surface (/api/v1/*) and the MCP streamable-HTTP transport (/mcp) on the same port. Single container, single port mapping, single healthcheck.
• Embedding-failure degradation. When the embedding provider goes 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.
• Optional operational metrics. Released images (since v3.4.0) include the bounded Prometheus recorder and guarded /metrics endpoint, off by default. Opt in with OC_METRICS_ENABLED=true; enabling it in production stays subject to the performance gates. See the metrics configuration and the optional local monitoring runbook.
• Schema migration framework. Versioned .sql migrations with savepoint atomicity. Re-runs are idempotent. Future schema changes drop in as NNN_<slug>.sql files.
• Verified online backups. Uses SQLite's online backup API; each nightly snapshot is published with a verified manifest in OC_BACKUP_DIR, and one that fails verification is quarantined. Backup-before-destructive policy: vacuum runs a backup first as part of the same job. Integrity-check failures trigger emergency backups.
• Optional encrypted offsite copies. A nightly job encrypts the newest snapshots with age and copies them to any rclone remote, append-only. See cloud_backup.md.

What it isn't

• Not a conversation engine. v3 has no LLM. Use Claude Code, Goose, Open WebUI, etc. via the MCP server.
• Not multi-tenant. Single user. Bearer-token auth via OC_API_KEY is supported but optional — disabled by default for trusted-LAN deployments. See docs/configuration/security_posture.md for the when-to-enable guidance.
• Not a cloud sync layer. The DB lives on your hardware. Backups go to a local backup directory and, optionally, encrypted to a cloud remote, as backup only. Cross-device sync isn't built in (docs/design/0001-cloud-backup.md).

By design.

Install

From source:

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

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

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

OC_API_HOST=0.0.0.0 is required in a container — the app default binds container-loopback, which the port mapping can't reach. To call the server by anything other than localhost (a NAS hostname, a LAN IP), also set OC_MCP_ALLOWED_HOSTS=your-host:* or every request gets a 421 (see env_vars.md).

For a Portainer stack on a NAS, use the docker-compose.nas.yml at the repo root. It needs three things first: OC_TAG set to a release tag (there is no :latest fallback), the data volume created once (docker volume create openchronicle-mcp_oc-data; the compose never creates it, so a missing volume fails the deploy instead of starting empty), and the host exports directory created and owned by uid 1000. The file's header comments list every variable.

Quickstart

# Bootstrap the runtime treeoc init
# Create a projectPROJECT_ID=$(oc init-project "my-project")
# Save your first memoryoc memory add "Decision: SQLite for storage; AGPL for license" \    --project-id $PROJECT_ID --tags decision
# Search itoc memory search "storage decision" --project-id $PROJECT_ID

Or do the same via MCP — register the server with Claude Code:

claude mcp add --scope user --transport http openchronicle \    http://127.0.0.1:8000/mcp

Then ask Claude to call memory_save and memory_search.

Architecture

Hexagonal: domain/ (pure types + ports) → application/ (use cases, services) → infrastructure/ (SQLite, embedding adapters, the maintenance loop). Driver-side adapters in interfaces/ host the HTTP, MCP, and CLI surfaces.

See docs/architecture/ARCHITECTURE.md for the full layout.

Documentation

• docs/architecture/ARCHITECTURE.md — layout, schema, ASGI design
• docs/architecture/MAINTENANCE.md — maintenance loop + degradation policy
• docs/cli/commands.md — oc subcommand reference
• docs/configuration/env_vars.md — environment variables
• docs/configuration/config_files.md — core.json schema
• docs/configuration/security_posture.md — security model
• docs/integrations/mcp_client_setup.md — register the MCP server
• docs/integrations/mcp_server_spec.md — MCP tool surface
• docs/api/STABILITY.md — versioning + deprecation policy
• docs/design/README.md — proposed designs and comparative repository reviews

Development

uv sync --locked --extra dev --extra mcp --extra openai --extra ollama --extra metricspre-commit installuv run pytest

Dependencies are locked in uv.lock, which CI and the Docker image install from; run uv lock after changing anything in [project] in pyproject.toml, including the version.

The architecture is enforced by tests:

• tests/test_hexagonal_boundaries.py — domain/application/infrastructure layering
• tests/test_architectural_posture.py — core agnostic of MCP SDK
• tests/test_no_secrets_committed.py, tests/test_no_soft_deprecation.py — repo hygiene

License

Copyright (C) 2025-2026 CarlDog

AGPL-3.0. This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed WITHOUT ANY WARRANTY; see the license for details.

The copyright line lives here rather than inside LICENSE: that file is the AGPL text verbatim, and the <year> <name of author> placeholders in its closing appendix are the license's own instructions for what to put in your source files — not blanks to fill in. Editing them would modify the license text itself.