openchronicle-mcpCAUTION
Memory database for LLM agents — persistent keyword + optional semantic memory, project namespacing, served over HTTP REST and MCP from a single ASGI process. SQLite-backed, packaged as a Docker container. Runs on your hardware.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
· claude-fable-5 · 2026-08-30 · details
[](LICENSE) [](https://ghcr.io/carldog/openchronicle-mcp) [](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. Released images (since v3.4.0) include
the bounded Promet
e3177964eaf7OBSERVED · 2026-10-10Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add openchronicle-mcp-tools --env OC_API_KEY=${OC_API_KEY} --env OC_GIT_TOKEN=${OC_GIT_TOKEN} --env OPENAI_API_KEY=${OPENAI_API_KEY} -- npx -y [email protected]{
"mcpServers": {
"openchronicle-mcp-tools": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"OC_API_KEY": "${OC_API_KEY}",
"OC_GIT_TOKEN": "${OC_GIT_TOKEN}",
"OPENAI_API_KEY": "${OPENAI_API_KEY}"
}
}
}
}Exposed tools (23)
15 read · 5 write · 3 destructive. Blast radius: 3 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
context_recent | read | Catch up on prior context for a project: returns recent memory items. |
db_backup_create | write | Create one consistent SQLite snapshot in the exposed manual backup directory. |
db_backup_list | read | List completed local SQLite snapshots, newest first. |
db_backup_verify | read | Check one snapshot |
db_restore_plan | read | Compare a verified snapshot with the running database before restore. |
db_restore_stage | read | Copy and reverify one candidate on the database volume for offline recovery. |
health | read | Probe the OC server: DB reachability, config status, embedding subsystem. |
memory_delete | destructive | Preview or hard-delete a memory item. |
memory_embed | read | Generate embeddings for memories that lack them (or regenerate all). |
memory_get | read | Fetch a single memory by ID. |
memory_list | read | Browse memory items — enumeration, distinct from relevance search. |
memory_pin | read | Mark a memory as pinned (or unpin it). |
memory_save | write | Persist a memory item that should outlive the current session. |
memory_search | read | Find memory items relevant to a query (hybrid semantic + keyword). |
memory_stats | read | Summarize memory contents: total/pinned counts, breakdowns by tag and source. |
memory_update | write | Edit an existing memory |
onboard_git | read | Bootstrap project memory from a remote git repo |
project_create | write | Create a new project namespace for memories. |
project_delete | destructive | Preview or hard-delete a project and all its memories. |
project_delete_bulk | destructive | Preview or hard-delete several projects and all their memories. |
project_get | read | Fetch a single project by id. |
project_list | read | List projects, newest first, with id, name, and creation timestamp. |
project_update | write | Rename a project or update its metadata. |
Trust audit
CAUTIONgrade B · trust 86/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (5 observation(s))
- Network
- declared (8 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (21)
CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/health',timeout=3).status==200 else 1)"memory_delete, project_delete, project_delete_bulk
.gitleaks.toml
.markdownlint-cli2.jsonc
.markdownlint.json
.pre-commit-config.yaml
@pytest.mark.parametrize("artifact_id", ["../secret", "manual:../../secret", "auto:bad", "/tmp/x.db"])"https://169.254.169.254/latest/meta-data", # metadata endpoint
claude mcp add --scope user --transport http openchronicle http://127.0.0.1:8000/mcp
claude mcp add --scope user --transport http openchronicle http://127.0.0.1:8000/mcp
http://127.0.0.1:8000/mcp
http://127.0.0.1:8000/mcp
chunk = base64.b64decode(match[5], validate=True)
markdownlint-cli2
| 315 | 2026-10-03 | **QUAL-22 and QUAL-26: metric labels, and the MCP endpoint served at exactly `/mcp`** (post-merge finding from #100, widened by the pre-deploy review of #109; affects `main` and v
| 169 | 2026-08-29 | **ADR 0009 implementation merged to `main` (fast-forward to `0ad0e50d`, 844 tests) + the ADR's implementation note recorded.** The mandated live OpenAI capture FALSIFIED the ADR's
- **Offline / write-behind sync for LAN-unreachable clients.** OC's single-user home-LAN posture (no auth, NAS-only, per `docs/configuration/security_posture.md`) means any client MCP call fails outri
| **File-based configuration** (single `core.json`, three-layer precedence) | Working | All subsystems wired: routing, budget, retry, privacy, telemetry, conversation, Discord. Secrets (API keys, bot
**Dropbox.** No app review for a single-user app (production approval only past 50 linked users), refresh tokens with no documented expiry, `Retry-After` always present on 429, and App Folder is the n
**Why encrypt — corrected justification. Considered and rejected: the scope critique's claim that recommending Dropbox App Folder makes encryption redundant.** That argument conflates *token scope* wi
do not export the live corpus or load the credential vault.
Gates applied: no_behavioural_pass.
e3177964eaf7full audit observations/trust-audit/mcp-server/carldog__openchronicle-mcp.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-10 | e3177964eaf7 | CAUTION | B | 86 | first audit |
Questions
What is the openchronicle-mcp MCP server?
Memory database for LLM agents — persistent keyword + optional semantic memory, project namespacing, served over HTTP REST and MCP from a single ASGI process. SQLite-backed, packaged as a Docker container. Runs on your hardware.
What tools does openchronicle-mcp expose?
23 in total: 15 read-only, 5 that write, and 3 that can delete or overwrite (memory_delete, project_delete, project_delete_bulk). Every one is listed on this page with its risk.
Is openchronicle-mcp safe to connect to an agent?
With care. The audit graded it B (86/100) and found 21 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 3 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does openchronicle-mcp need?
It reads OC_API_KEY, OC_GIT_TOKEN and OPENAI_API_KEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does openchronicle-mcp run?
It speaks sse, stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as openchronicle-mcp-tools at 1.0.0.
How current is this page?
The grade is for one exact copy of the source (e3177964eaf7), read on 2026-10-10. The repository is watched and re-audited when it changes.