# openchronicle-mcp [Health: Active] **Category:** ๐Ÿ—„๏ธ Databases **Repository:** https://github.com/CarlDog/openchronicle-mcp **GitHub Stars:** 16 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/openchronicle-mcp ## Description Memory database for LLM agents โ€” persistent semantic + keyword memory, project namespacing, served o ## Claude Desktop Quick Installation Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client: ```json "mcpServers": { "openchronicle-mcp": { "url": "https://img.shields.io/badge/code_confidence-fair-orange" } } ``` ## Documentation & README # OpenChronicle ![code confidence](https://img.shields.io/badge/code_confidence-fair-orange) ยท claude-fable-5 ยท 2026-08-30 ยท [details](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/../../issues/27) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io%2Fcarldog%2Fopenchronicle--mcp-blue?logo=docker)](https://ghcr.io/carldog/openchronicle-mcp) [![Python 3.14+](https://img.shields.io/badge/Python-3.14%2B-blue?logo=python&logoColor=white)](https://python.org) 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.** The standard image includes the bounded Prometheus recorder and guarded `/metrics` endpoint. Enable it explicitly with `OC_METRICS_ENABLED=true`; it remains off by default. See the [metrics configuration](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/configuration/env_vars.md) and the optional [local monitoring runbook](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/monitoring/runbook.md). - **Schema migration framework.** Versioned `.sql` migrations with savepoint atomicity. Re-runs are idempotent. Future schema changes drop in as `NNN_.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`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/design/0001-cloud-backup.md). By design. ## Install From source: ```bash 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): ```bash 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](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/configuration/env_vars.md)). For a Portainer stack on a NAS, use the `docker-compose.nas.yml` at the repo root. ## Quickstart ```bash # 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: ```bash 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`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/architecture/ARCHITECTURE.md) โ€” layout, schema, ASGI design - [`docs/architecture/MAINTENANCE.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/architecture/MAINTENANCE.md) โ€” maintenance loop + degradation policy - [`docs/cli/commands.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/cli/commands.md) โ€” `oc` subcommand reference - [`docs/configuration/env_vars.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/configuration/env_vars.md) โ€” environment variables - [`docs/configuration/config_files.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/configuration/config_files.md) โ€” `core.json` schema - [`docs/configuration/security_posture.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/configuration/security_posture.md) โ€” security model - [`docs/integrations/mcp_client_setup.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/integrations/mcp_client_setup.md) โ€” register the MCP server - [`docs/integrations/mcp_server_spec.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/integrations/mcp_server_spec.md) โ€” MCP tool surface - [`docs/api/STABILITY.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/api/STABILITY.md) โ€” versioning + deprecation policy - [`docs/design/README.md`](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/docs/design/README.md) โ€” proposed designs and comparative repository reviews ## Development ```bash 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](https://github.com/CarlDog/openchronicle-mcp/blob/HEAD/LICENSE). 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 ` ` 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.