openchronicle-mcp

OpenChronicle

_{· claude-fable-5 · 2026-08-30 · details}

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 (unreleased). Development and benchmark 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 OC_METRICS_ENABLED=true; the default stays off. 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.
• Atomic online backups. Uses SQLite's online backup API. Backup-before-destructive policy: vacuum runs a backup first as part of the same job. Integrity-check failures trigger emergency backups.

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 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.

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 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.

Quickstart

# Bootstrap the runtime tree
oc init

# Create a project
PROJECT_ID=$(oc init-project "my-project")

# Save your first memory
oc memory add "Decision: SQLite for storage; AGPL for license" \
    --project-id $PROJECT_ID --tags decision

# Search it
oc 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

pip install -e ".[dev,mcp,openai,ollama]"
pre-commit install
pytest

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.