mindswap
Keep project context and personal AI memory local so tools can continue work without re-explaining the same context.
Why it exists
AI sessions reset too often. mindswap saves the current task, decisions, blockers, and handoff context so the next tool can pick up cleanly.
Install
npm install mindswap --save-dev
Quick start
npx mindswap init
npx mindswap
npx mindswap doctor
npx mindswap resume
npx mindswap ask "Why did we choose JWT?"
What it gives you
initto set up a repo and import existing AI contextsaveto capture the current task, git state, and decisionsdoctorto check setup health and stale contextresumeto start with a clean briefingaskto search project memory with citationsmemoryto manage blockers, assumptions, questions, and resolutions--globalmemory and ask scope for personal cross-tool memory under~/.mindswap/reindexto rebuild the local SQLite search index from your file-based memorysyncto share continuity state across machinesmcpandmcp-httpto expose the same context to AI clients
Global personal memory
MindSwap now supports two local memory scopes:
- repo memory in
<repo>/.mindswap/ - personal memory in
~/.mindswap/
Use global memory when a preference or learning should follow you across projects and tools.
npx mindswap log "Prefer concise explanations" --type assumption --global
npx mindswap memory list --scope all
npx mindswap ask "What explanation style should we use?" --scope all
npx mindswap reindex --scope all
MCP and AI tools
mindswap generates context for tools like Claude Code, Cursor, Copilot, Codex, Windsurf, Cline, Roo, Aider, Amp, Gemini CLI, and AGENTS.md-based workflows.
npx mindswap mcp-install
npx mindswap mcp-http
Project state
The main repo data lives in .mindswap/:
.mindswap/
├── HANDOFF.md
├── state.json
├── decisions.log
├── memory.json
├── config.json
├── branches/
└── history/
npm package
Use it
If mindswap helps your workflow, star the repo and keep improving the handoff loop.