OpenChronicle

code confidence · claude-fable-5 · 2026-07-06 · details

License: AGPL-3.0 Docker Python 3.11+

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 /health. Backfill catches up when the provider returns.
  • 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 (see V3_PLAN.md open question 12 for the design sketch).

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 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config \
  ghcr.io/carldog/openchronicle-mcp:latest

For a Portainer stack on a NAS, use the docker-compose.nas.yml at the repo root.

Quickstart

# Bootstrap the runtime tree
oc init
oc init-config

# 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

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

AGPL-3.0.