About Mindswap
Mindswap is a local-first context and memory server for developers and coding agents, designed to carry project state and decisions across sessions. Its CLI saves and searches memory, creates handoff briefings, and can share context with AI clients through MCP.
Key features
- 01Save tasks, Git state, and decisions
- 02Resume work with handoff briefings
- 03Search memory with citations
- 04Manage blockers, assumptions, and questions
- 05Separate project and personal memory scopes
- 06Sync state across machines
Use cases
- 01Resume a coding task in a later session
- 02Find the rationale behind a project decision
- 03Carry personal preferences across projects
- 04Share project context with AI clients
MCP support
Mindswap exposes project and personal context to AI clients through MCP commands, including mcp and mcp-http. It also provides an MCP installation command.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
4Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| focus | enum | No | What to focus on: "all" for full context, "task" for current work only, "decisions" for architecture decisions, "recent" for latest changesall | task | decisions | recent |
| compact | boolean | No | Return token-optimized compact format (fewer tokens, same info) |
Details
From the project READMEmindswap
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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.