@mindpouch/index-sqlite

Mindpouch

Your notes are the memory. Agents just get to use them.

Mindpouch is a local-first memory layer for AI agents, built on a folder of Markdown you already own — an Obsidian vault, a notes directory, any pile of .md files. Agents get fast recall that's honest about how much to trust each piece of context. You keep plain files you can read, edit, move, and version like you always have.

npm install -g mindpouch
mindpouch setup agent --vault ~/notes
mindpouch recall "what did I decide about the standing desk"

Why agent memory?

Agents are becoming long-lived collaborators — they research your purchases, track your projects, write your code across weeks. But every session starts from zero. You re-explain what you're working on, what you decided last month, what you already ruled out, which option you preferred and why. The context you've painstakingly built up evaporates the moment the conversation ends.

Memory is what turns an assistant into your assistant: one that opens with "last time you narrowed it to two monitors" instead of "what can I help you with today?"

Why your notes should be the memory

Most agent memory systems solve this with a database the agent writes to and you can't meaningfully open. That trade has hidden costs that compound:

• You can't audit what it "knows" about you. Wrong beliefs get extracted silently, persist invisibly, and shape every future answer.
• You can't correct what you can't see. There's no red pen for an opaque embedding store.
• Your accumulated memory is hostage to one vendor's schema, one service's uptime, one product's lifespan.

Mindpouch inverts the design. The memory is your Markdown:

• Files stay canonical. Recall reads from an index, but the index is disposable — delete it any time and rebuild from your notes. Nothing you'd miss lives only in a database.
• Every write is a file you can see. "Remember this" creates a new note in your inbox (dry-run first). Accepting an extracted fact writes it into the relevant note's frontmatter. git status on your vault after an agent session shows exactly what changed — usually nothing.
• Nothing becomes "known" silently. Facts extracted from prose are proposals with evidence, waiting for your accept/reject. Your decisions are journaled in the vault itself and survive index rebuilds and file moves.
• Your organization is signal, not obligation. Folders, links, and tags inform retrieval; nothing forces a taxonomy on you. Move files freely.

What it's good for

• "What did I decide about X?" — project decisions, buying research, prior conclusions, with the source note cited.
• Durable context agents should just know — preferences, constraints, ongoing projects — kept where you can edit it when it changes.
• Explicit capture: "remember this" lands as a reviewable note, never a hidden row.
• Relationship questions: "how does X relate to Y?", "what do I know about Alice?" — answered from links, tags, and reviewed typed edges, not vibes.
• One memory across agents: the same vault serves Claude Code (via MCP), Hermes (as a native provider), skill-based agents, scripts, and you at the terminal.

What it deliberately is not (yet): automatic conversation capture (turns are never recorded silently — that's a policy, not a gap), embedding/semantic search (recall is lexical + graph + recency today), or a hosted service (everything runs on your machine).

Privacy

A vault holds more than an agent should see — journals, health notes, other people's confidences. Mindpouch fences those off at index time, so excluded content never enters the database at all (not filtered at query time — simply never stored):

---
private: true        # this note is never indexed
---

# these paths are never even read
mindpouch setup agent --vault ~/notes --exclude "journal/,health/,people/therapist.md"

Marking an already-indexed note private: true removes it (and its entities) on the next reindex. mindpouch doctor reports what's being excluded — and warns if you accidentally exclude your own capture directory.

Quick Start

npm install -g mindpouch

# One-time: index your vault and write a config file.
mindpouch setup agent --vault /path/to/vault

# Optional: make every later command flag-free from any directory.
export MINDPOUCH_CONFIG=/path/to/vault/.mindpouch/config.json

mindpouch doctor                    # health check
mindpouch recall "portable monitor" # agent-ready, epistemically labeled context
mindpouch remember "Chose the 15\" matte panel." --dry-run

Requires Node ≥ 22. Without MINDPOUCH_CONFIG, commands also find .mindpouch/config.json by searching upward from the current directory, and --config <path> always wins.

What recall looks like

Most memory systems answer "what is relevant?". Mindpouch's recall also answers "how much should you trust it?" and "what do I not know?" — in the payload itself, so any agent that reads it inherits the behavior:

# Mindpouch Recall

Query: standing desk setup for Quixotic Ventures

Lanes: evidence = source-backed; experience = events/observations; synthesis = derived summaries; belief = current view, not verified.

## [1] Standing Desk
Source: Standing Desk.md # Standing Desk
Lane: evidence
Reason: better-sqlite3-fts5; recency x1.25; score=2.8550

- Bought for: [[Demo Note]]
It works with [[Filename Title Note]] nicely.

## Related notes (accepted relationships)
- Standing Desk -[bought_for]-> Demo Note (notes/Demo Note.md)

## Confirmed false (user-rejected proposals — do not assume these)
- Standing Desk -[works_with]-> Filename Title Note (rejected 2026-07-02)

## Coverage gaps (what the vault does not establish)
- No entity note found for "Quixotic Ventures".
- No note matches all query terms; the results above match only some of them.

Four layers, each doing a distinct job:

Epistemic lanes. Every block declares whether it is evidence (source-backed), experience (events/observations), synthesis (derived summaries), or belief (the user's current view, not verified). Set a note's lane with lane: belief in frontmatter, or mindpouch remember "<text>" --lane belief. An agent told "this is a belief, not evidence" reasons differently — and says so.

Confirmed-false guardrails. When you reject an extracted fact, the rejection is remembered — and recall actively warns agents off it: do not assume this; the user rejected it. Confirmed-false is stored knowledge here, not mere absence. We don't know of another memory system that serves negative knowledge at recall time.

Coverage gaps. Recall states what the vault does not establish: named entities with no note, results that only partially match, staleness ("newest matching note is 400 days old"). Explicit absence is one of the strongest anti-hallucination signals you can hand a model — an agent told "your notes don't cover X" says that instead of guessing.

Recency-aware, budget-respecting ranking. Recently updated notes get a gentle boost (visible in each block's Reason: line — ranking stays explainable), and no single note may crowd everything else out of the context budget.

The review loop: prose → proposals → your call

Mindpouch can notice relationships written in your notes — but nothing becomes graph truth without you:

# 1. Scan. Deterministic extractors read lines like "- Depends on: [[X]]"
#    and "[[Alice]] works with [[Bob]]" — no LLM, same result every run.
mindpouch propose relationships

# 2. Inspect, with evidence. Ids abbreviate to any unique prefix.
mindpouch proposals --status proposed --min-confidence 0.8

# 3. Preview the exact edit, then accept.
mindpouch accept relationship proposal_ba4a10ea --dry-run
# Would add to Standing Desk.md: rel_bought_for: ["[[notes/Demo Note]]"]
mindpouch accept relationship proposal_ba4a10ea

# 4. Reject what's wrong — journaled, never re-proposed, and recall
#    will warn agents not to assume it.
mindpouch reject relationship proposal_3d3d0f3e

Accepting writes the edge into the subject note's own frontmatter — the knowledge graph lives in your Markdown, so a from-scratch index rebuild loses nothing. Rejections append to <vault>/.mindpouch/decisions.jsonl, keyed by the fact itself rather than file paths, so decisions survive rebuilds and note moves.

Sentence subjects are attributed properly: [[Alice]] works with [[Bob]] proposes an Alice→Bob edge (accepting writes into Alice's note), not an edge from whichever note the sentence happens to sit in — and candidates whose subject can't be resolved are dropped rather than mis-attributed.

You can also declare relationships directly in frontmatter, no review needed — they're yours:

---
rel_researched_for: ["[[Mindpouch POC]]"]
relationships:
  - depends_on: "[[Projects Hub]]"
---

Inspect the graph with probe <entity>, relate --from <x> --to <y>, relationships, links, backlinks, and tags.

Using it from agents

Mode	Coexists with other memory providers	Best for
MCP server	yes	Claude Code, IDEs, any MCP host
Skills + CLI	yes	skill-capable agents, scripts, humans
Hermes provider	replaces the active external provider	automatic per-turn prefetch in Hermes

All three are thin adapters over one engine and share one config file.

MCP — register the stdio server with any MCP host:

{
  "mcpServers": {
    "mindpouch": {
      "command": "npx",
      "args": ["-y", "@mindpouch/mcp", "--config", "/path/to/.mindpouch/config.json"]
    }
  }
}

14 tools: recall, search, remember, probe, relationships, relate, links, tags, the four proposal-review tools, status, and index. The server reindexes incrementally on startup; add --reindex-seconds 300 to refresh before reads when the index is stale.

Hermes — Mindpouch as the active external memory provider: labeled context prefetched before every turn, provider-owned tools, and turns never captured — git status on your vault stays clean unless you explicitly asked to remember something. Prefetch is precision-gated (it injects only when a note matches every query term), so unrelated turns cost zero tokens. Install via packages/adapters-hermes.

Skills — mindpouch setup skills --target <agent-skills-dir> copies first-party skills that teach recall-before-answering, how to read the epistemic labels, explicit-only capture, and the proposal-review policy.

How it works

Your vault is parsed (Obsidian-compatible: wiki links, frontmatter, aliases, tags, CRLF, unicode) into a local SQLite/FTS5 index — incrementally, skipping unchanged files by content hash. An engine package owns all operations; the CLI, MCP server, and Hermes provider are presenters over it. Everything derived is rebuildable from the vault plus its decisions journal.

Package	What it is
mindpouch	the CLI (this is the one you install)
@mindpouch/mcp	MCP stdio server
@mindpouch/engine	operational core — build your own adapter on this
@mindpouch/core, @mindpouch/vault, @mindpouch/index-sqlite	types/contracts, Markdown layer, index backend

Command reference

mindpouch setup agent --vault <path> [--index <path>] [--config <path>]
mindpouch index                        # incremental reindex
mindpouch search <query> [--scope <path-prefix>]
mindpouch recall <query> [--limit <n>]
mindpouch remember "<text>" [--lane evidence|experience|synthesis|belief] [--dir inbox] [--dry-run]
mindpouch links <path> | backlinks <path> | tags [path]
mindpouch entities [query] | probe <entity> | relate --from <x> --to <y>
mindpouch relationships [entity] [--predicate <p>] [--direction inbound|outbound|both]
mindpouch propose relationships
mindpouch proposals [--status proposed|accepted|rejected] [--min-confidence <0..1>]
mindpouch accept relationship <id> [--dry-run]
mindpouch reject relationship <id>
mindpouch doctor

Every command takes --json for machine-readable output — those JSON shapes are the compatibility surface (see CHANGELOG.md).

Development

git clone https://github.com/rjsamson/mindpouch && cd mindpouch
pnpm install
pnpm -r build && pnpm -r test && pnpm -r typecheck
python3 -m unittest discover packages/adapters-hermes/tests   # Hermes provider tests

CI runs the full suite on macOS, Linux, and Windows. For agent-led setup from a checkout, see the agent install runbook; Hermes integration details live in docs/hermes-integration-plan.md.

License

MIT