🧠 Mind

Stop losing context across sessions, tools, and time. Give your AI workflow a memory that lasts.

Mind is a local memory layer for AI workflows: a persistent memory system for durable context such as decisions, bug fixes, patterns, checkpoints, and session summaries that would otherwise disappear across sessions and tools.

It supports recovery after compaction through checkpoint and session continuity behavior, while giving humans a way to visualize, inspect, and modify that memory through the CLI and web UI.

Why Mind works above the fold:

• Local persistent store. One SQLite-backed memory system you control.
• Built for agent workflows. Use it through the CLI, MCP server, HTTP API, and web UI.
• Resumption tools included. Checkpoints and session summaries help recover context and continue work.
• Optional file sync. Experimental autosync can mirror project spaces into versioned .mind/ files.
• Search when you need it. Full-text search is built in, and semantic search is available as an optional add-on.

Get started with Installation or jump straight to the Quick start.

Why try Mind?

Mind helps you keep durable context organized, retrievable, and usable as work moves across tools, sessions, and compaction boundaries.

• Structured memory you can revisit. Organize information into spaces, tags, directional links, tiers, pins, checkpoints, and session summaries.
• Recovery built into the workflow. Restore context after compaction, resume work from checkpoints, and keep important state visible over time.
• Shared interfaces, one memory layer. Use the CLI, MCP server, HTTP API, and web app against the same local source of truth.
• Per-space visibility with Neural Map. Each space includes a read-only graph view so you can understand how memories connect without claiming a global knowledge graph.

What is Mind?

Mind is a Bun + TypeScript project that provides a CLI, an MCP server, an HTTP API, and a web UI on top of one local SQLite memory store (mind.db). It uses FTS5 full-text search, metadata filters, tags, links, and a 3-tier memory model (T1 hot, T2 warm, T3 cold) to keep saved context useful over time.

If you want semantic search, you can enable optional OpenAI embeddings. They are off by default.

Installation

You can install Mind quickly and start using it right away. If you want agent setup later, jump to Agent setup.

One-line installer (recommended)

curl -fsSL https://raw.githubusercontent.com/GabrielMartinMoran/mind/main/scripts/install.sh | bash

This installs Mind to user-local paths (no sudo):

• app: ~/.local/share/mind
• launcher: ~/.local/bin/mind

Then run:

mind help

The installer creates a launcher that runs the installed src/mind.ts entry point. It doesn't configure every supported agent automatically. To refresh existing mind-managed agent integrations after installation, run mind setup refresh.

Requirements

• Bun 1.2+ (auto installed by the one-line installer if not present)

Install from source

git clone https://github.com/GabrielMartinMoran/mind.git
cd mind
bun install

Quick start

This is the fastest way to see what Mind feels like in practice.

# Create a project space
mind create projects/my-project "My project"

# Add a memory
mind add projects/my-project architecture "CLI uses command registry + atomic command modules"

# Search across memories
mind search architecture

# Start the web UI
mind serve start
# Open http://localhost:30303

Agent setup

Mind supports multiple agent integrations, but they are not all equally mature. Run mind setup without an agent name to see the current capability matrix, then configure the specific agent you want.

mind setup              # show capability matrix first
mind setup claude-code
mind setup opencode
mind setup cursor
mind setup codex
mind setup windsurf
mind setup gemini-cli
mind setup vscode
mind setup antigravity
mind setup refresh      # refresh detected mind-managed integrations

mind setup refresh is conservative by default. It refreshes only detected integrations, where detection means mind finds an existing mind-owned signal, such as an MCP config, managed protocol block, hook/plugin/script, or installed mind-management skill. Use --dry-run to preview changes, --all to refresh all supported agents, or --agent <name> to target one agent.

Post-install configuration

Most configuration is optional. You only need extra setup if you want to change paths, ports, or enable semantic search.

1. Create your .env file:

cp .env.example .env

Mind ships with a .env.example that contains all configurable options. The installer will also do this automatically if .env doesn't exist.

2. Configure environment variables (optional):

Edit .env to customize your setup:

RAG / semantic search setup:

To enable AI-powered semantic search:

# In .env:
MIND_RAG=true
OPENAI_API_KEY=sk-your-key-here

When enabled, memories are embedded using OpenAI's text-embedding-3-small model and combined with full-text search for hybrid retrieval.

Basic CLI example

mind create projects/mind "Mind project memory"
mind add projects/mind architecture "CLI uses command registry + atomic command modules"
mind search architecture

For the full command list:

mind help

Usage

CLI

mind help
mind create <space> "description"
mind update <space> --hidden
mind list --hidden
mind add <space> <name> "content"
mind list <space>
mind read <space> <name>
mind checkpoint set <space> "goal" "pending"
mind checkpoint recover <space> --name <checkpoint-name>
mind checkpoint complete <space> <name> "what was done"
mind migrate sessions projects/<repo> --dry-run
mind checkpoint list <space> --status active
mind search "query"
mind query --space <space> --from 2026-01-01 --to 2026-12-31 --limit 20 --offset 0
mind update --check
mind update

Autosync (Experimental)

Autosync lets you mirror project spaces to a versioned .mind/ directory so you can review memory files in git, edit markdown on disk, and sync those changes back into the local database. When a space is enabled, successful DB mutations made through the CLI, web/API, or MCP also export the affected space back to .mind/spaces/<hash>/ as a non-blocking side effect.

[!NOTE] This is an experimental feature currently under active development.

Set up autosync with the following flow:

1. Run mind sync init to create .mind/config.yml and .mind/.gitignore.
2. Review or edit .mind/config.yml to choose which spaces are configured.
3. Run mind sync enable --space <name> for the project space you want to sync.
4. Optional: Run mind sync serve --space <name> to start the watcher in the current terminal, or rely on MCP startup to auto-start watchers for enabled spaces.

The .mind/ directory uses a file-based config and hashed space directories:

.mind/
├── config.yml
├── .gitignore
└── spaces/
    └── a1b2c3d4/
        ├── manifest.json
        └── memory-name.md

Use these commands to manage autosync:

• mind sync init
• mind sync status
• mind sync enable --space <name>
• mind sync disable --space <name>
• mind sync now --space <name>
• mind sync export --space <name>
• mind sync import --space <name>
• mind sync conflict --space <name> --strategy <strategy>
• mind sync remove --space <name>
• mind sync config
• mind sync serve --space <name>

Conflict strategies:

• db-wins writes the DB version on real conflicts and prunes only files that the manifest marks as managed.
• file-wins preserves the file side on real conflicts. Automatic DB-to-file exports skip the conflicting file and record a warning.
• latest-wins uses normalized UTC timestamps as a tie-break after hash-based dirty detection. Near-future timestamps within five minutes are accepted for clock skew, while farther future timestamps are reported as unsafe and skipped instead of blindly overwriting.

Autosync writes manifest v2 files. Each manifest entry tracks managed file ownership, the memory name, path, optional DB ID, canonical content and metadata hashes, normalized UTC timestamps, file modification time, and the last sync time. Hashes decide whether the DB side, file side, both sides, or neither side changed since the common baseline. A file's mere existence isn't a conflict.

Example .mind/config.yml:

# mind autosync config

version: 1

# Spaces to sync with this project
# To enable a new space, add it below with enabled: true
# Valid conflictResolution values: db-wins, file-wins, latest-wins
spaces:
  # projects/mind:
  #   enabled: true
  #   conflictResolution: db-wins

Current limitations and caveats:

• mind sync status --space <name> reports DB, file, and manifest counts, dirty DB/file drift, conflicts, tombstones, missing managed files, and the latest auto-export warning or error when manifest data is available.
• Existing-memory imports update supported metadata from files when the conflict strategy chooses file-to-DB: content, tags, tier, pinned state, and links_to links. Invalid metadata skips that file safely, unresolved links are reported, and frontmatter name does not rename