Install:
pipx install mindkeep(orpip install mindkeep) · See Getting Started · 中文版 快速上手
Crash-safe, per-project long-term memory for AI coding agents. Zero runtime dependencies · SQLite + WAL · Python ≥ 3.9 · MIT
Give your agents a real memory: facts, ADRs, preferences and session recaps
that survive across runs, machines and Ctrl-C. All stored locally in plain
SQLite files you can read, back up or git diff.
- 🔒 Crash-safe — WAL + 30s flush, survives SIGKILL
- 🗂 Per-project isolation — one SQLite file per repo hash
- 🔍 Ranked recall —
mindkeep recall <query>over FTS5 + bm25 (CJK-friendly) - 📌 Pin priority — pinned facts/ADRs always surface first, survive token budgets
- 🪙 Token-aware —
--budget Ncaps rendered output by token count; per-session budget viaMINDKEEP_SESSION_BUDGET - 🛡 Write guard — dual-threshold cap (facts ≤ 100 / ADRs ≤ 1500 tokens) blocks runaway writes
- 🩺 Doctor —
mindkeep doctorruns 8 health checks (schema, WAL, FTS5, cap pressure, …) - 🔌 Drop-in agent integration —
mindkeep integrate <claude|copilot|cursor|generic>emits a ready-to-paste snippet - 🌐 Global preferences — user tastes follow you across projects
- 🔐 Secrets redactor — 11 credential patterns scrubbed by default
- 🪶 stdlib-only core — no deps at runtime,
pipstays quiet - 📦 JSON export/import — portable, inspectable, diffable
One-line curl | bash / iwr | iex is convenient but executes remote code blindly.
For anything production-sensitive, download first, review, then run:
Windows (PowerShell):
iwr https://github.com/AllenS0104/mindkeep/releases/latest/download/install.ps1 -OutFile install.ps1
# open install.ps1 in your editor and review it, then:
.\install.ps1macOS / Linux:
curl -fsSL https://github.com/AllenS0104/mindkeep/releases/latest/download/install.sh -o install.sh
# open install.sh in your editor and review it, then:
bash install.shEvery GitHub Release ships a
SHA256SUMS file alongside the wheel / sdist / install scripts, so you can pin
to a tagged version and verify integrity:
curl -fsSL -o SHA256SUMS https://github.com/AllenS0104/mindkeep/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing# PowerShell equivalent
Get-FileHash -Algorithm SHA256 .\install.ps1
# compare the output against the matching line in SHA256SUMSpipx install mindkeep # preferred — isolated venv, on PATH
# or, if you don't have pipx:
pip install --user mindkeepThat's it. mindkeep is a stdlib-only Python package — no compilation, no native deps.
Windows (PowerShell):
iwr https://raw.githubusercontent.com/AllenS0104/mindkeep/main/install.ps1 | iexmacOS / Linux:
curl -fsSL https://raw.githubusercontent.com/AllenS0104/mindkeep/main/install.sh | bashThe installer checks Python ≥ 3.9, installs pipx if missing, runs
pipx install mindkeep, ensures pipx's bin dir is on your PATH,
and runs mindkeep doctor so you know it works.
Grab the .whl + SHA256SUMS from the Releases page:
pip install --user ./mindkeep-0.3.0-py3-none-any.whlmindkeep --version
mindkeep doctorA day in the life of an AI coding agent that doesn't lose its mind on Ctrl-C. Reads use the CLI; writes use the Python one-liner (the CLI is intentionally read-only — agents call the API directly).
# === Session 1 — agent opens a checkout API repo ===
$ cd ~/code/checkout-api
$ mindkeep where
data_dir: ~/.local/share/mindkeep · project=7c4e1a9f0b3d
# agent thinking: "before I touch anything, what do I already know?"
$ mindkeep show --kind facts --limit 20
(no rows yet)
# agent thinking: "user just confirmed JWT RS256 over HS256. Persist it."
$ python -c "from mindkeep import MemoryStore; \
s = MemoryStore.open(); \
s.add_fact('auth.method: JWT RS256 — rotated quarterly via KMS', tags=['auth','security']); \
s.add_adr('RS256 over HS256', \
decision='Use asymmetric JWT signing (RSA-256).', \
rationale='Downstream services verify without sharing the secret.'); \
s.close()"
# === ~~~ ⚡ process killed (laptop sleep / SIGKILL / OOM) ~~~ ===
# === Session 2 — agent reboots, same repo ===
$ cd ~/code/checkout-api
$ mindkeep show --kind facts
content="auth.method: JWT RS256 — rotated quarterly via KMS" tags=auth,security 2026-04-27T09:42:11Z
# agent thinking: "good, I remember. Continue where I left off."
# === Session 3 — agent switches to a different repo ===
$ cd ~/code/admin-portal
$ mindkeep where
data_dir: ~/.local/share/mindkeep · project=2e8b6d04ac17 ← different ID
$ mindkeep show --kind facts
(no rows yet) ← admin-portal has its own memory, untainted by checkout-apiEach repo gets its own SQLite file. Crash, switch context, reboot — your agent's memory follows the project.
mindkeep ships with a built-in snippet generator. Pick your agent, paste, done:
mindkeep integrate copilot >> ~/.copilot/AGENTS.md
mindkeep integrate claude >> ~/.claude/CLAUDE.md
mindkeep integrate cursor >> .cursorrules
mindkeep integrate generic # vendor-neutral markdown to stdoutEach snippet tells the agent to:
- Load prior context at session start (
mindkeep show --kind facts|adrs|sessions) - Run targeted lookups before non-trivial answers (
mindkeep recall "<query>") - Persist durable signal proactively (facts, ADRs, preferences)
- Skip silently when mindkeep isn't installed
Run mindkeep integrate --list to see all targets. The pattern (recall on start, store on decision) generalizes — feel free to fork the snippet for any other tool.
Full CLI surface and Python API are in docs/USAGE.md.
Full docs live in docs/ — start at the portal for role- and task-based navigation.
| Guide | One-liner |
|---|---|
| INSTALL | 4 ways to install, enterprise & air-gap, doctor diagnostics |
| USAGE | CLI reference + Python API + 8 cookbook recipes |
| UNINSTALL | Backup, removal, PATH restore, compliance exit |
| FAQ | 22 questions across 5 categories |
| TROUBLESHOOTING | 19 symptoms in symptom / cause / diagnose / fix form |
See also: ARCHITECTURE.md · CHANGELOG.md · CONTRIBUTING.md
Fourteen subcommands, all --help-friendly:
list list all known projects
show show rows for a project (--kind facts|adrs|preferences|sessions|all)
clear delete rows from a project
pin pin a fact or ADR so it surfaces first
unpin remove the pinned flag from a fact or ADR
export dump a project to JSON
import load a JSON dump into a project
where print data_dir and current project id
doctor run environment health checks (schema, WAL, FTS5, cap, …)
stats print introspection stats for a project
recall full-text search across facts and ADRs (FTS5 + bm25)
upgrade pull the latest mindkeep (pip/pipx auto-detected)
integrate emit an AI-agent integration snippet (claude|copilot|cursor|generic)
session inspect or reset the per-shell token-budget state
One full example — inspect the current repo's memory:
cd ~/code/my-app
mindkeep where # → C:\Users\you\AppData\Roaming\mindkeep · project=a1b2c3d4e5f6
mindkeep show --kind facts --limit 5
mindkeep export ./my-app-memory.jsonfrom mindkeep import MemoryStore
with MemoryStore.open() as store: # resolves project from cwd
store.add_fact("stack: Postgres 15 + FastAPI", tags=["stack"])
store.add_adr("use RSA-256 for JWT",
decision="Sign JWTs with RS256.",
rationale="Asymmetric keys let downstream services verify without sharing the secret.")
store.set_preference("style.quote", "single", scope="user")
for row in store.list_facts(tag="stack"):
print(row["value"])The store auto-flushes every 30 seconds, on close(), and on atexit /
SIGTERM. Secrets are redacted before they hit disk.
┌─────────────────────────────────────────────────────────────┐
│ Your agent process │
│ │
│ MemoryStore ─► SecretsRedactor ─► SQLite (WAL mode) │
│ │ │ │
│ └── flush scheduler (30s) ─────────┘ │
└──────────────────────────┬──────────────────────────────────┘
▼
<data_dir>/
├── projects/
│ ├── a1b2c3d4e5f6.db ← repo A (hashed path)
│ ├── a1b2c3d4e5f6.meta.json
│ └── 9f8e7d6c5b4a.db ← repo B
└── preferences.db ← cross-project user tastes
- Project ID = first 12 hex chars of
sha256(git-remote || abs-path) data_dir=%APPDATA%\mindkeep\(Windows),~/Library/Application Support/mindkeep/(macOS), or$XDG_DATA_HOME/mindkeep/(Linux). Override with$MINDKEEP_HOME.- Crash safety = WAL +
synchronous=NORMAL+ atomic rename for.meta.json+atexit/SIGTERMflush hooks
See ARCHITECTURE.md for the full contract and ADRs.
The 4 most-asked questions are inline below. For the full 22-question FAQ (getting started, usage, security, internals, troubleshooting) see docs/FAQ.md.
Q: If I Ctrl-C the CLI, do I lose data?
A: No. WAL mode flushes on every commit; the 30-second scheduler plus
atexit / SIGTERM hooks guarantee durability. SIGKILL is safe too —
SQLite replays the WAL on next open.
Q: Is it safe to store prompts and errors in here?
A: Yes. SecretsRedactor is on by default and scrubs 11 classes of
credentials before write: PEM private keys, JWTs, GitHub PATs (classic +
fine-grained), AWS access & secret keys, Google API keys, Slack tokens,
OpenAI keys, Azure storage keys, plus a generic password|token|api_key=…
sweep. Still — don't store secrets on purpose.
Q: I installed it but mindkeep isn't found.
A: Run python -m mindkeep doctor — it prints the exact PATH it
expects. Usually it's fixed by opening a new terminal (installers edit
PATH for future shells). See docs/TROUBLESHOOTING.md for more.
Q: How do I upgrade / uninstall?
A: mindkeep upgrade (auto-detects pipx vs pip). To remove: pipx uninstall mindkeep.
Your data in data_dir is not deleted — see docs/UNINSTALL.md for a clean wipe.
git clone https://github.com/AllenS0104/mindkeep.git
cd mindkeep
pip install -e ".[dev]"
pytestPRs welcome — please run pytest and keep the stdlib-only rule for
src/mindkeep/ (dev-deps are fine).
MIT — see LICENSE.
Built by Allen Song (@AllenS0104) with help
from a fleet of AI sub-agents (architect, coder, ops, PMO, UX inspector — see
.github/agents/). The stdlib-only constraint is intentional: a memory layer
shouldn't depend on a memory of dependencies.
Issues, ideas, PRs welcome at github.com/AllenS0104/mindkeep/issues.