# Changelog The JSON output shapes of the CLI (`--json`), the MCP tool results, and the engine's public API are the compatibility surface: breaking changes to them bump the minor version while we are pre-1.0, and the major version after. ## Unreleased Two compatibility surfaces change (per the policy above, the next release is 0.2.0): the recall TEXT format renders note snippets as blockquotes (`> `) — JSON shapes are unchanged, and `blocks[].snippet`/`title` and `openQuestions[].title` remain raw note content by contract (consumers rendering them into structured output must apply their own fencing); and `IndexStore` gains a required `dataVersion(): Promise` method (breaking for third-party store implementers). - Correctness wave from the full-codebase audit. Recall text now fences note content: snippets render as blockquotes and titles inline, so vault content can never forge the structural sections agents trust ("## Confirmed false", "## Coverage gaps" — a note containing them reads as quoted content). Search is Unicode-aware: CJK and accented queries work (the old tokenizer returned zero results for 東京). Parsing: `# comment` lines inside code fences are no longer headings/titles/chunk boundaries; markdown link targets may contain spaces and parentheses; symlinked notes and directories are indexed (with cycle protection); numeric frontmatter dates (`created: 2024`) fall back to file stats instead of becoming 1970 timestamps. Engine: relative config paths resolve against the config's location (project root for `.mindpouch/config.json`), not the invocation cwd; entity coverage gaps no longer fire on possessives ("Alice's"), Title-Case phrases, or first-name references to existing full-name notes; question ids resolve by slug prefix without the date; the question cache detects other processes' index writes (`IndexStore.dataVersion`, new contract method), so a long-lived MCP server sees CLI-filed questions. Stores: per-file delete+insert sequences are transactional (a failed insert can no longer permanently strip a file's rows); a new id claiming an existing path evicts the old row in both stores identically (contract-tested); `LIKE` escaping handles backslashes; `file_id` indexes on links/tags/mentions/relationships remove O(N²) reindex scans. CLI: numeric flags reject typos with clear errors (previously `--min-confidence 0.5x` silently hid every proposal); parse errors print one line, not a stack trace; `--help` works per command; `--` marks everything after it positional; `entities --entity` works; help documents `--lane`. Hermes: free prose is passed after `--` so text starting with dashes survives; `mindpouch_questions` tolerates the ask-style `about` array; the prefetch executor is race-safe and in-flight background prefetches are awaited instead of duplicated; session starts no longer re-run setup when the shared config already points at the same vault. ## 0.1.2 - Critical hardening from a full-codebase audit: frontmatter editors can no longer corrupt notes (YAML comments merge safely, block-scalar values replace cleanly, indented `---` is not a closer, and every edit is verified to reparse before writing — a corrupt frontmatter previously dropped `private: true`); edge dedupe compares exact entries, not substrings; `setup agent` re-runs merge the existing config instead of silently resetting `exclude` (which could index private directories) and `consolidation`; interrupted indexing self-heals (content hash committed last); accept/reject journal before touching the rebuildable index and the journal tolerates torn appends; config and note rewrites are atomic (temp+rename); CLI boolean flags reject `--dry-run=yes`-style values instead of silently performing real writes; the Hermes provider never breaks a turn on missing tool params, operator config typos, or non-UTF-8 locales. - Prospective memory — open questions: `mindpouch ask` files a question as an ordinary vault note (`type: question`, default `questions/` dir, configurable via `setup agent --questions-dir`); recall surfaces open questions in a capped "Open questions" section whenever the topic strictly comes up, by wording or by `about`-entity overlap (alias-aware via the entity table), while filtering open question notes out of the context blocks (an intention never masquerades as knowledge; single-shared-word any-term overlaps do not count as the topic). Answered questions flip to ordinary knowledge — the recorded `## Answer` surfaces as a normal block. `answer --with/--note` closes with provenance (status is checked against the note on disk, so hand-reopening in Obsidian works without a reindex); `drop --reason` retires without deleting. The section cap is a recall request option (`--max-questions`, `maxOpenQuestions`, 0 disables). New MCP tools `mindpouch_ask` / `mindpouch_questions` / `mindpouch_answer` / `mindpouch_drop_question` (19 total); Hermes provider mirrors them and prefetch injects on question-only strict matches, rendered as questions alone, with granular operator config (`inject_questions`, `inject_questions_alone`, `inject_questions_max`) implemented through the recall request. CLI: `--about` repeats per entity (names may contain commas) and `--flag=value` syntax supports values starting with `--`. JSON compatibility surface gains `RecallResult.openQuestions`; doctor warns when the questions directory is excluded from indexing (independently of the capture-dir warning). - Consolidation, phase 1 — supersession proposals: `propose consolidation` deterministically detects stale-twin note pairs (kindred titles + content overlap + age gap; thresholds configurable via `consolidation.minOverlap` / `consolidation.minAgeGapDays`). Accepting marks the older note `status: superseded` / `superseded_by` in frontmatter (nothing deleted or moved; hand-written `status: superseded` frontmatter has the same effect); recall then skips superseded notes visibly ("Superseded notes skipped" section, `supersededSkipped` in JSON, capped at 4) while direct search still reaches them. When a query's only matches are superseded notes, recall reports it as a coverage gap; superseded chunks never crowd live matches out of the candidate window. Chains stay clean: a note that is itself superseded is never offered as a replacement. The detector's tokenizer is `\w`-based, so it is inert for unsegmented scripts (CJK) — a documented limitation. - The proposal store is now multi-kind (`kind: relationship | supersession` with kind-scoped queries, pruning, and an optional kind-specific JSON `payload` — supersession proposals carry `{overlap, gapDays, oldUpdated, newUpdated}`); existing `relationship_proposals` tables migrate automatically on first open (orphaned legacy rows are skipped, never brick the index). Breaking for `IndexStore` implementers: the proposal methods are renamed (`upsertProposals`, `listProposals`, `setProposalStatus`, `pruneProposals`). Engine API: `acceptProposal` / `rejectProposal` / `proposals` (renamed from their `relationship*` forms). CLI: `accept|reject relationship|supersession ` (bare `accept ` still works for any kind), `proposals --kind`. MCP and the Hermes provider: new propose-consolidation tool and `kind` on the proposal list/accept/reject tools. - Decision-journal identity is kind-aware: relationship decisions replay by normalized triple (durable across note moves); supersession rejections replay by triple + both note paths (a decision is about one specific pair — same-titled pairs elsewhere in the vault are unaffected); accepted supersessions are journaled for audit but never replayed — the note's own frontmatter is the durable record. - Recall eval harness: 20 known-answer cases against a realistic fixture vault (recency, lanes, aliases, privacy, gaps, relationships, confirmed-false), run in CI as the regression gate for ranking and recall behavior. ## 0.1.1 - Privacy scoping, enforced at index time: notes with `private: true` frontmatter are never indexed (and are removed on reindex if they become private); config-level `exclude` path prefixes (set via `setup agent --exclude "a/,b/"`) are never even read. Doctor reports private-note counts and configured excludes, and warns when the capture directory is excluded. - Rewritten README (why agent memory, why notes-as-memory, privacy, npm-based quick start) now ships on the npm package page. ## 0.1.0 Initial public release. - Local-first indexing of Markdown/Obsidian vaults (better-sqlite3 + FTS5), incremental by content hash, with config auto-discovery (`$MINDPOUCH_CONFIG` or a `.mindpouch/config.json` found upward from cwd). - Epistemically labeled recall: per-block memory lanes (evidence/experience/synthesis/belief), recency-boosted ranking, per-file context caps, any-term fallback with honest labeling. - Relationship layer: links, tags, entities, mentions, typed frontmatter relationships; `probe`, `relate`, `relationships` queries. - Reviewable relationship proposals from prose (deterministic extractors, subject attribution); accepting writes the edge into the subject note's frontmatter, rejecting is journaled in the vault (`.mindpouch/decisions.jsonl`) and survives index rebuilds. - Confirmed-false guardrails and coverage-gap reporting in recall output. - Explicit memory writes (`remember`, dry-run first); no automatic capture, ever. - Integrations: `mindpouch` CLI, `mindpouch-mcp` MCP stdio server (14 tools), Hermes external-memory-provider plugin, and first-party skills.