100 % local, zero vendor lock-in. PostgreSQL 17 + pgvector + FastAPI + Ollama (default
bge-m3, switchable to any catalog model —qwen3-embedding:8b,mxbai-embed-large, … — from Settings). No API keys, no hosted dependencies, completely free to run on your own machine.
MindBase is the memory substrate of the AIRIS Suite - providing persistent, semantic conversation history across all AI coding assistants.
| Component | Purpose | For Who |
|---|---|---|
| airis-agent | 🧠 Intelligence layer for all editors (confidence checks, deep research, self-review) | All developers using Claude Code, Cursor, Windsurf, Codex, Gemini CLI |
| airis-mcp-gateway | 🚪 Unified MCP proxy with 90% token reduction via lazy loading | Claude Code users who want faster startup |
| mindbase (this repo) | 💾 Local cross-session memory with semantic search | Developers who want persistent conversation history |
| airis-workspace | 🏗️ Docker-first monorepo manager | Teams building monorepos |
| airiscode | 🖥️ Terminal-first autonomous coding agent | CLI-first developers |
- airis-mcp-supabase-selfhost - Self-hosted Supabase MCP with RLS support
- mindbase (this repo) - Memory search & storage tools (
mindbase_search,mindbase_store)
MindBase comes pre-configured with AIRIS MCP Gateway. No additional setup required.
# One command installs everything
curl -fsSL https://raw.githubusercontent.com/agiletec-inc/airis-mcp-gateway/main/scripts/quick-install.sh | bashIf you need to run MindBase independently:
git clone https://github.com/agiletec-inc/mindbase.git ~/github/mindbase
cd ~/github/mindbase
cp .env.example .env && uv sync --all-packages && docker compose up -d postgres
uv run python -m uvicorn apps.api.main:app --reload --port 18003 # see Quick start belowWhat you get with the full suite:
- ✅ Confidence-gated workflows (prevents wrong-direction coding)
- ✅ Deep research with evidence synthesis
- ✅ 94% token reduction via repository indexing
- ✅ Cross-session memory across all editors
- ✅ Self-review and post-implementation validation
MindBase is the durable conversation memory service that the AIRIS MCP Gateway taps into. AIRIS acts as the gateway and tool orchestrator, while MindBase focuses on storing and retrieving conversations with semantic recall. That separation keeps responsibilities crisp:
- AIRIS MCP Gateway – registers any MCP server (including MindBase), handles the "tool roster" problem by lazily streaming tool descriptions to the LLM, and keeps overall context windows under control.
- MindBase – provides the
mindbase_searchandmindbase_storeMCP tools plus an HTTP API. It runs as a Mac-friendly Docker stack so your editors, agents, and AIRIS can persist or query conversations without touching the cloud.
Because AIRIS only loads tool instructions when the model actually chooses MindBase, you avoid the hot-load issue where twenty richly documented tools explode the prompt budget. MindBase simply exposes concise capabilities; AIRIS decides when and how to surface them.
- Unified timeline – Collectors pull logs from editors, desktop clients, terminal agents, and any bespoke transcripts. Everything lands in one ordered ledger so you can replay how a project evolved across assistants.
- Project & topic intelligence – Stored metadata keeps conversations grouped by project, topic, and source. You can trace a task from brainstorming in Claude Desktop to implementation inside Cursor without manual tagging.
- Semantic memory – Messages are embedded locally through Ollama (default
bge-m3, switchable per the model catalog) and stored in pgvector. Vectors from different models coexist per conversation, so you can re-embed and compare models. MindBase becomes the long-term recall layer for AIRIS tools, MCP servers, or any downstream automation. - Local-first privacy – Conversations reside only inside your Dockerized PostgreSQL volume. Nothing writes to
~/Library/Application Supportor remote services, so your chat history never leaks into cloud sync folders.
┌──────────────────────────────────────────────────────────────────────────┐
│ Menubar App (Swift/SwiftUI) ✨ Auto-Collection │
│ - File system watcher (FSEvents) for conversation directories │
│ - Auto-triggers collectors on new conversation detection │
│ - Toggle: ✓ Auto-Collection Enabled │
│ - Health monitoring with status indicators (🟢🟡🔴) │
└───────────────┬──────────────────────────────────────────────────────────┘
│ Auto-runs Python collectors
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Collectors (Python) │
│ - Cursor / Windsurf / VS Code logs │
│ - Claude Desktop / Claude Code exports │
│ - ChatGPT / Gemini / terminal agent transcripts │
│ - Custom ingestion scripts (`collectors/`) │
└───────────────┬──────────────────────────────────────────────────────────┘
│ JSON payloads → /conversations/store
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ MindBase FastAPI (`apps/api`) │
│ - POST /conversations/store │
│ - POST /conversations/search │
│ - GET /health │
└───────────────┬──────────────────────────────────────────────────────────┘
│ SQL + vector writes
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ PostgreSQL 17 + pgvector (Docker volume `postgres_data_dev`) │
│ - Structured metadata (projects, topics, sources, timestamps) │
│ - Embedding vectors (1024‑dim) │
└───────────────┬──────────────────────────────────────────────────────────┘
│ local embedding calls
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Ollama (default bge-m3 · switchable model) │
│ - Fully on-device │
│ - Runs free of charge │
└───────────────┬──────────────────────────────────────────────────────────┘
│ MCP tool bridge
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ AIRIS MCP Gateway │
│ - Registers MindBase tools │
│ - Streams tool descriptions lazily to LLMs │
│ - Keeps prompt context efficient │
└──────────────────────────────────────────────────────────────────────────┘
Requirements: Docker (OrbStack works), uv, and a host Ollama. The API runs host-native; only Postgres runs in Docker.
# 1. Clone (adjust the destination if needed)
git clone https://github.com/agiletec-inc/mindbase.git ~/github/mindbase
cd ~/github/mindbase
# 2. Copy environment defaults
cp .env.example .env
# 3. Install Python deps into one workspace venv (uv reads .python-version → 3.12)
uv sync --all-packages
# 4. Pull the embedding model once into your host Ollama
ollama pull bge-m3
# 5. Start Postgres (pgvector). Migrations in supabase/migrations/ apply
# automatically on first volume init.
docker compose up -d postgres
# 6. Run the API on the host (talks to the host Ollama over localhost)
uv run python -m uvicorn apps.api.main:app --reload --port 18003
# 7. Check health (in another shell)
curl -fsS http://localhost:18003/health # → ok ; interactive docs at /docs
# 8. (Optional) Run the raw derivation worker
uv run python -m apps.api.workers.raw_deriverAll conversation data lives in the PostgreSQL volume declared in compose.yml (postgres_data_dev). Remove that volume (docker compose down -v) when you want a clean slate; nothing is written to random App Support folders.
A lightweight native Swift / SwiftUI menu bar app that automatically collects AI conversations from Claude Code, Cursor, Windsurf, and ChatGPT. It monitors conversation directories and triggers collectors on file changes.
Features:
- Auto-Collection Toggle: Enable/disable via menu bar (✓ Auto-Collection Enabled)
- File System Watcher: Monitors
~/.claude/,~/.cursor/,~/Library/Application Support/Windsurf/, etc. - Auto-Collector Execution: Runs Python collectors when new conversations are detected
- Health Monitoring: Shows API, database, and Ollama status (🟢🟡🔴)
- Quick Commands: One-click
docker compose up -d postgres/ API start / logs
Setup:
# Homebrew (recommended)
brew tap agiletec-inc/tap
brew install mindbase-menubar
# Or build from source — see apps/menubar-swift/README.mdLook for the MindBase icon in your macOS menu bar. Click "Auto-Collection Disabled" to toggle ON. The watcher will start monitoring conversation directories and automatically run collectors when new files are detected.
Use Settings… to update the API base URL, workspace root, repository path, and custom collector definitions (changes sync to API via /settings endpoint).
Store a conversation
curl -X POST http://localhost:18003/conversations/store \
-H "Content-Type: application/json" \
-d '{
"source": "cursor",
"title": "Fix flaky CI pipeline",
"project": "platform",
"topic": "deployments",
"occurred_at": "2025-10-30T08:45:00Z",
"content": {
"messages": [
{"role": "user", "content": "Why is the staging deploy stuck?"},
{"role": "assistant", "content": "Investigating build logs..."}
]
},
"metadata": {
"editor": "Cursor",
"branch": "fix-staging-deploy"
}
}'Run a semantic search
curl -X POST http://localhost:18003/conversations/search \
-H "Content-Type: application/json" \
-d '{
"query": "autonomous PM agent reflection pattern",
"limit": 8,
"threshold": 0.75,
"source": "all",
"project": "superclaude"
}'Responses include similarity scores, timestamps, metadata, and the original messages so AIRIS (or any client) can immediately cite the relevant history.
- AIRIS MCP Gateway – Run
make installinside the AIRIS repo (orsuperclaude install) to exposemindbase_searchandmindbase_store. The gateway advertises only the selected tool to the LLM, keeping prompts minimal while MindBase delivers embeddings and payloads on demand. - Collectors (
collectors/) – Python scripts and templates that read local caches (Claude, Cursor, ChatGPT, Windsurf, etc.), normalize them, and push JSON to/conversations/store. Extend them to cover any other assistant or internal agent you run. - Processors & Generators (
libs/) – TypeScript utilities that transform stored conversations into knowledge packs, retrospectives, or other artifacts. They demonstrate how MindBase can power downstream workflows. - Schema & migrations (
supabase/) – SQL migrations for PostgreSQL live here so the same schema can be applied locally (via Docker) or to a managed Postgres instance. There is no hosted Supabase dependency; the directory simply keeps schema history tidy.
- Conversations, embeddings, and metadata stay inside the Docker-managed Postgres volume. Stop the stack with
docker compose downand the data remains on disk in thepostgres_data_devvolume. - All embeddings are generated locally through Ollama, so you never leak prompts or code to third-party APIs.
- If you need off-device backups, dump the database (
pg_dump) or replicate the Docker volume; there is no hidden shadow copy under~/Library/Application Support.
- More collectors for enterprise chat / ticketing tools.
- Automated summarization and recap views for long-running projects.
- MCP-side incremental recall so AIRIS can page in only the slices of memory that the LLM asks for.
- Fine-grained retention and redaction policies per source.
- Export pipelines that turn curated threads into blogs, books, or playbooks.
- Fork the repo and create a feature branch.
- Follow the style guides in
docs/,AGENTS.md, andCLAUDE.md. - Run the validations before opening a PR:
uv run pytest tests/ -v uv run black --check apps/api/ libs/collectors/ && uv run ruff check apps/api/ libs/collectors/ pnpm lint - Open the PR with a Conventional Commit title, describe the change, list the commands you ran, and attach API traces or screenshots when relevant.
Explore other tools in the AIRIS ecosystem:
- airis-mcp-gateway - Unified MCP hub with 90% token reduction
- airis-agent - Intelligence layer for AI coding (confidence checks, deep research)
- airis-mcp-supabase-selfhost - Self-hosted Supabase MCP with RLS support
- airis-workspace - Docker-first monorepo manager
- cmd-ime - macOS IME switcher (Cmd key toggle)
- neural - Local LLM translation tool (DeepL alternative)
- airiscode - Terminal-first autonomous coding agent
MindBase is released under the MIT License.
agiletec is a one-person studio building these tools full-time and open source. If they earn a spot in your workflow, a sponsorship keeps them maintained and independent.
Built with ❤️ by the Agiletec team