@danielmarbach/mnemonic-mcp 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `mnemonic` will be documented in this file.
 
 The format is loosely based on Keep a Changelog and uses semver-style version headings.
 
+## [0.5.0] - 2026-03-12
+
+### Changed
+
+- **Self-describing tools — no system prompt required.** All 22 MCP tools now include detailed descriptions with "use when" / "do not use when" decision boundaries, follow-up tool hints, and side-effect documentation. Tool-level `annotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) are set on every tool. Parameter descriptions are enriched with semantics, examples, and guidance (e.g. `lifecycle`, `summary`, `cwd`, `scope`). The 141-line `SYSTEM_PROMPT.md` has been replaced by a one-liner fallback — models discover correct behavior from tool metadata alone.
+- Upgraded `zod` to `^4.3.6` and aligned schema declarations with Zod v4's stricter `z.record` signature to keep MCP structured-output validation and type-checking consistent.
+
+## [0.4.1] - 2026-03-11
+
+### Added
+
+- Docker image published to `danielmarbach/mnemonic-mcp` on Docker Hub for `linux/amd64` and `linux/arm64`. Tagged with the release version and `latest`.
+
+### Fixed
+
+- `list_migrations` now returns structured content that matches its declared MCP output schema. The handler already included `totalPending`, but the zod schema omitted it, causing the tool to fail with a structured-content validation error instead of listing migrations.
+
 ## [0.4.0] - 2026-03-11
 
 ### Added

package/README.md

@@ -12,6 +12,8 @@ For the high-level system map, see [`ARCHITECTURE.md`](ARCHITECTURE.md). For rel
 - 🎯 Project-scoped recall surfaces the right repo context first while keeping global memories accessible.
 - 🤝 Shared `.mnemonic/` notes travel with the repository, so project knowledge isn't trapped in one person's chat history.
 - 🔒 Embeddings stay local and gitignored — semantic search without committing generated vector data.
+- 📝 Every `remember`, `update`, and `consolidate` creates a semantic git commit — decision log and plans travel with the code in the same history.
+- 🔓 Designed for removability — though we're quietly confident you won't use that exit. Every note is plain markdown with YAML frontmatter; the knowledge you gather is independent of mnemonic and always yours.
 
 ## Stability
 
@@ -75,9 +77,11 @@ Override the vault location:
 VAULT_PATH=/path/to/your-vault docker compose run --rm mnemonic
 ```
 
-## Installing from npm
+## Installing
 
-Packages are published to the public npm registry. No authentication required.
+### npm
+
+Published to the public npm registry. No authentication required.
 
 ```bash
 # Latest stable release
@@ -87,6 +91,17 @@ npm install @danielmarbach/mnemonic-mcp
 npm install @danielmarbach/mnemonic-mcp@0.2.0
 ```
 
+### Docker Hub
+
+Pre-built images for `linux/amd64` and `linux/arm64`:
+
+```bash
+docker pull danielmarbach/mnemonic-mcp:latest
+
+# Or a specific version
+docker pull danielmarbach/mnemonic-mcp:0.5.0
+```
+
 ## MCP client config
 
 ### Claude Desktop / Cursor (native)
@@ -138,6 +153,38 @@ For a fixed installed version, point at the local binary instead:
 
 > Ollama must be running before the MCP client invokes mnemonic. Start it once with `docker compose up ollama -d` and it will stay up between calls.
 
+### OpenCode
+
+Add to `~/.config/opencode/opencode.json` (global) or `opencode.json` in your project root:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "mnemonic": {
+      "type": "local",
+      "command": ["npx", "@danielmarbach/mnemonic-mcp"],
+      "environment": {
+        "VAULT_PATH": "/Users/you/mnemonic-vault"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+Add to `~/.codex/config.toml` (global) or `.codex/config.toml` in a trusted project:
+
+```toml
+[mcp_servers.mnemonic]
+command = "npx"
+args = ["@danielmarbach/mnemonic-mcp"]
+
+[mcp_servers.mnemonic.env]
+VAULT_PATH = "/Users/you/mnemonic-vault"
+```
+
 For local development against this repository's source tree, use `npm run mcp:local` or point your MCP client at `scripts/mcp-local.sh`.
 
 ## Configuration
@@ -149,6 +196,28 @@ For local development against this repository's source tree, use `npm run mcp:lo
 | `EMBED_MODEL` | `nomic-embed-text-v2-moe` | Ollama embedding model           |
 | `DISABLE_GIT` | `false`                   | Set `true` to skip all git ops   |
 
+### config.json
+
+The main vault's `~/mnemonic-vault/config.json` holds machine-local settings that survive across sessions. You can edit it by hand — unknown fields are ignored and invalid values fall back to defaults.
+
+User-tunable fields:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `reindexEmbedConcurrency` | `4` | Parallel embedding requests during `sync` (capped 1–16) |
+| `mutationPushMode` | `"main-only"` | When to auto-push after a write: `"all"`, `"main-only"`, or `"none"` |
+
+`projectMemoryPolicies` and `projectIdentityOverrides` are written automatically by `set_project_memory_policy` and `set_project_identity` — no need to edit them by hand.
+
+Example — raise concurrency on a fast machine and disable auto-push everywhere:
+
+```json
+{
+  "reindexEmbedConcurrency": 8,
+  "mutationPushMode": "none"
+}
+```
+
 ## How it works
 
 ### Vault layout
@@ -361,6 +430,16 @@ After the first sync, call `sync` (with `cwd` for project vaults) whenever you s
 
 ## FAQ
 
+**Is the advantage over plain markdown files and grep just easier search?**
+
+Easier search is part of it, but three things work together:
+
+- **Semantic search over vector embeddings.** Each note is locally indexed via Ollama so `recall` finds the right note even when you don't remember the exact words — searching "JWT expiry bug" can surface a note titled "RS256 migration rationale". `grep` only matches strings you already know.
+- **A connected knowledge graph.** Notes link to each other with typed relationships (`explains`, `supersedes`, `example-of`). Related context surfaces together automatically; `memory_graph` shows the full web. A folder of markdown files has no edges between them.
+- **Decision history travels with the code.** Every `remember`, `update`, and `consolidate` creates a descriptive git commit, so your decision log and implementation plans evolve alongside the code they describe — attributed and timestamped in `git log`.
+
+mnemonic is designed to be removable — so give it a try with confidence. We think once you do, you'll stay. But if you ever leave, all the knowledge you've gathered is independent: plain markdown with standard YAML frontmatter, readable in any editor, searchable with `grep`, committable to git. No rescue operation required.
+
 **Are mnemonic's embeddings the same as what Claude uses?**
 
 No. The embeddings here are **local vector representations** generated by Ollama on your machine — nothing is sent to Anthropic or any cloud service. They are produced by a small embedding model (`nomic-embed-text-v2-moe` by default) and stored as plain JSON files. This is the same idea as retrieval-augmented generation (RAG): each note is converted to a dense numeric vector so `recall` can find semantically related notes even when you don't remember the exact words you used. It has nothing to do with how Claude processes tokens internally.
@@ -388,4 +467,8 @@ build/     Compiled JavaScript output
 
 ## Agent instructions
 
-See [`SYSTEM_PROMPT.md`](SYSTEM_PROMPT.md) for the system prompt to use with your MCP client.
+No system prompt required. Mnemonic's tools are self-describing — each includes "use when" / "do not use when" guidance, behavioral annotations, and typed schemas. Models will use them correctly from tool metadata alone.
+
+If your model isn't picking up the tools proactively, add this one-liner to your AGENT.md or system prompt:
+
+> You have access to a long-term memory system via the `mnemonic` MCP server. Use it proactively — don't wait to be asked.