{
  "markdown": "# OpenChronicle\r\n\r\n<!-- markdownlint-disable MD033 -->\r\n<!-- fleet-confidence -->\r\n![code confidence](https://img.shields.io/badge/code_confidence-fair-orange) <sub>· claude-fable-5 · 2026-08-30 · [details](../../issues/27)</sub>\r\n<!-- /fleet-confidence -->\r\n<!-- markdownlint-enable MD033 -->\r\n\r\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)\r\n[![Docker](https://img.shields.io/badge/Docker-ghcr.io%2Fcarldog%2Fopenchronicle--mcp-blue?logo=docker)](https://ghcr.io/carldog/openchronicle-mcp)\r\n[![Python 3.14+](https://img.shields.io/badge/Python-3.14%2B-blue?logo=python&logoColor=white)](https://python.org)\r\n\r\nA memory database for LLM agents. Persistent semantic + keyword\r\nmemory, project namespacing, git-onboard, served over HTTP REST and\r\nMCP from a single ASGI process. Runs on your hardware.\r\n\r\n## What it does\r\n\r\n- **Persistent memory across sessions.** Save decisions, milestones,\r\n  and rejected approaches that survive context compression and new\r\n  conversations. Retrieve them with hybrid full-text and semantic\r\n  search via Reciprocal Rank Fusion.\r\n- **Project namespacing.** Memory is scoped to projects, so context\r\n  for one workstream doesn't leak into another.\r\n- **Git onboarding.** Clone a repo, cluster commits by relatedness,\r\n  return summaries ready for memory ingestion. Seeds long-term memory\r\n  with the WHY behind existing code.\r\n- **One process, two transports.** FastAPI hosts both the REST surface\r\n  (`/api/v1/*`) and the MCP streamable-HTTP transport (`/mcp`) on the\r\n  same port. Single container, single port mapping, single\r\n  healthcheck.\r\n- **Embedding-failure degradation.** When the embedding provider goes\n  down, search degrades cleanly to FTS5-only and surfaces the\n  degraded state via `/api/v1/health` and the MCP `health` tool.\n  Backfill catches up when the provider returns; the static `/health`\n  endpoint remains a minimal liveness probe.\n- **Optional operational metrics.** The standard image includes the bounded\n  Prometheus recorder and guarded `/metrics` endpoint. Enable it explicitly\n  with `OC_METRICS_ENABLED=true`; it remains off by default. See the\n  [metrics configuration](docs/configuration/env_vars.md) and the optional\n  [local monitoring runbook](docs/monitoring/runbook.md).\n- **Schema migration framework.** Versioned `.sql` migrations with\n  savepoint atomicity. Re-runs are idempotent. Future schema changes\r\n  drop in as `NNN_<slug>.sql` files.\r\n- **Atomic online backups.** Uses SQLite's online backup API.\r\n  Backup-before-destructive policy: vacuum runs a backup first as\r\n  part of the same job. Integrity-check failures trigger emergency\r\n  backups.\r\n\r\n## What it isn't\r\n\r\n- Not a conversation engine. v3 has no LLM. Use Claude Code, Goose,\r\n  Open WebUI, etc. via the MCP server.\r\n- Not multi-tenant. Single user. Bearer-token auth via `OC_API_KEY`\r\n  is supported but optional — disabled by default for trusted-LAN\r\n  deployments. See `docs/configuration/security_posture.md` for the\r\n  when-to-enable guidance.\r\n- Not a cloud sync layer. The DB lives on your hardware. Backups go\r\n  to a directory next to it. Cross-device sync isn't built in; a\r\n  backup-only Dropbox design is documented but not implemented in\r\n  [`docs/design/0001-cloud-backup.md`](docs/design/0001-cloud-backup.md).\r\n\r\nBy design.\r\n\r\n## Install\r\n\r\nFrom source:\r\n\r\n```bash\r\npip install -e \".[mcp,openai]\"\r\noc init\r\noc serve\r\n```\r\n\r\nThe default `oc serve` binds `127.0.0.1:8000`. Override with\r\n`--host`/`--port` or `OC_API_HOST`/`OC_API_PORT`.\r\n\r\nDocker (single container, NAS-friendly):\r\n\r\n```bash\r\ndocker run --rm \\\r\n  -p 8000:8000 \\\r\n  -e OC_API_HOST=0.0.0.0 \\\r\n  -v $(pwd)/data:/app/data \\\r\n  -v $(pwd)/config:/app/config \\\r\n  ghcr.io/carldog/openchronicle-mcp:latest\r\n```\r\n\r\n`OC_API_HOST=0.0.0.0` is required in a container — the app default\r\nbinds container-loopback, which the port mapping can't reach. To call\r\nthe server by anything other than `localhost` (a NAS hostname, a LAN\r\nIP), also set `OC_MCP_ALLOWED_HOSTS=your-host:*` or every request gets\r\na 421 (see\r\n[env_vars.md](docs/configuration/env_vars.md)).\r\n\r\nFor a Portainer stack on a NAS, use the `docker-compose.nas.yml` at\r\nthe repo root.\r\n\r\n## Quickstart\r\n\r\n```bash\r\n# Bootstrap the runtime tree\r\noc init\r\n\r\n# Create a project\r\nPROJECT_ID=$(oc init-project \"my-project\")\r\n\r\n# Save your first memory\r\noc memory add \"Decision: SQLite for storage; AGPL for license\" \\\r\n    --project-id $PROJECT_ID --tags decision\r\n\r\n# Search it\r\noc memory search \"storage decision\" --project-id $PROJECT_ID\r\n```\r\n\r\nOr do the same via MCP — register the server with Claude Code:\r\n\r\n```bash\r\nclaude mcp add --scope user --transport http openchronicle \\\r\n    http://127.0.0.1:8000/mcp\r\n```\r\n\r\nThen ask Claude to call `memory_save` and `memory_search`.\r\n\r\n## Architecture\r\n\r\nHexagonal: `domain/` (pure types + ports) → `application/` (use cases,\r\nservices) → `infrastructure/` (SQLite, embedding adapters, the\r\nmaintenance loop). Driver-side adapters in `interfaces/` host the\r\nHTTP, MCP, and CLI surfaces.\r\n\r\nSee `docs/architecture/ARCHITECTURE.md` for the full layout.\r\n\r\n## Documentation\r\n\r\n- [`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) — layout, schema, ASGI design\r\n- [`docs/architecture/MAINTENANCE.md`](docs/architecture/MAINTENANCE.md) — maintenance loop + degradation policy\r\n- [`docs/cli/commands.md`](docs/cli/commands.md) — `oc` subcommand reference\r\n- [`docs/configuration/env_vars.md`](docs/configuration/env_vars.md) — environment variables\r\n- [`docs/configuration/config_files.md`](docs/configuration/config_files.md) — `core.json` schema\r\n- [`docs/configuration/security_posture.md`](docs/configuration/security_posture.md) — security model\r\n- [`docs/integrations/mcp_client_setup.md`](docs/integrations/mcp_client_setup.md) — register the MCP server\r\n- [`docs/integrations/mcp_server_spec.md`](docs/integrations/mcp_server_spec.md) — MCP tool surface\r\n- [`docs/api/STABILITY.md`](docs/api/STABILITY.md) — versioning + deprecation policy\r\n- [`docs/design/README.md`](docs/design/README.md) — proposed designs and comparative repository reviews\r\n\r\n## Development\r\n\r\n```bash\r\npip install -e \".[dev,mcp,openai,ollama]\"\r\npre-commit install\r\npytest\r\n```\r\n\r\nThe architecture is enforced by tests:\r\n\r\n- `tests/test_hexagonal_boundaries.py` — domain/application/infrastructure layering\r\n- `tests/test_architectural_posture.py` — core agnostic of MCP SDK\r\n- `tests/test_no_secrets_committed.py`, `tests/test_no_soft_deprecation.py` — repo hygiene\r\n\r\n## License\r\n\r\nCopyright (C) 2025-2026 CarlDog\r\n\r\n[AGPL-3.0](LICENSE). This program is free software: you can redistribute\r\nit and/or modify it under the terms of the GNU Affero General Public\r\nLicense as published by the Free Software Foundation, either version 3\r\nof the License, or (at your option) any later version. It is distributed\r\nWITHOUT ANY WARRANTY; see the license for details.\r\n\r\nThe copyright line lives here rather than inside `LICENSE`: that file is\r\nthe AGPL text verbatim, and the `<year> <name of author>` placeholders in\r\nits closing appendix are the license's own *instructions* for what to put\r\nin your source files — not blanks to fill in. Editing them would modify\r\nthe license text itself.\r\n",
  "bytes": 7247,
  "sha": "dbc5fdd78b62bddfd103760dcfc4175dac289702d8f9ecaa09441940368c4e13",
  "repo_slug": "carldog/openchronicle-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_csoai_org_openchronicle_mcp_cff3e717/readme"
}