memboot

Persistent memory for LLMs that works offline. No API keys. No servers. No cloud.

Every other memory tool requires an LLM call to store and retrieve, a managed API, or an HTTP server running in the background. memboot requires none of that. It's SQLite + TF-IDF on your local disk — works on an airplane, works in CI, works without giving a third party access to your codebase.

$ memboot init .
  Indexed 142 files, 1,847 chunks

$ memboot query "authentication flow"
  src/auth/jwt.py:create_token     0.89  "Creates signed JWT with user claims..."
  src/auth/middleware.py:verify     0.84  "Extracts and validates bearer token..."
  src/models/user.py:User          0.71  "User model with hashed password..."

$ memboot remember "Use JWT for API auth, sessions for web" --type decision
  Stored decision #14

$ memboot context "auth" --max-tokens 4000
  # Context: auth (3,842 tokens)
  ## src/auth/jwt.py
  ...

Features

• Smart chunking — AST-aware Python extraction, Markdown heading splits, YAML/JSON key-level, sliding window fallback
• Fully offline — Built-in TF-IDF embeddings with zero external dependencies. Optional sentence-transformers for semantic search
• Episodic memory — Store decisions, patterns, observations alongside your code index
• Context builder — Token-budgeted markdown blocks with optional local-Ollama reranking and smart context packs
• MCP server — Expose memory as tools for Claude Code, Cursor, Claude Desktop, Windsurf, Zed, OpenAI Codex CLI, mcphost, ollmcp, and LibreChat. memboot install --all-detected wires it into every client you have, zero config (integration details). The same memory store is shared across all clients — point Codex, Qwen-via-mcphost, and Claude at the same project and they all read/write the same context
• Zero-config install — One command writes the MCP entry into each client's config with automatic backup
• File ingestion — Ingest external files, PDFs, and web pages into project memory

Install

pip install memboot

Optional extras:

pip install memboot[embed]  # sentence-transformers for semantic embeddings
pip install memboot[mcp]    # MCP server support
pip install memboot[pdf]    # PDF ingestion
pip install memboot[watch]  # File watching for auto-reindex
pip install memboot[web]    # Web page ingestion
pip install memboot[secure] # SQLCipher DB encryption + encrypted notes sync

Quick Start

# Index a project
memboot init /path/to/your/project

# Search for relevant code and memories
memboot query "authentication flow" --project /path/to/your/project

# Store a decision
memboot remember "Use JWT for API auth, sessions for web" --type decision --project /path/to/your/project

# Store locally and mirror to a git-backed notes repo
memboot remember "Decided to use Redis for cache keys" \
  --type decision \
  --project /path/to/your/project \
  --notes-repo https://github.com/your-org/notes.git

# Pull notes from your git repo into local memboot memory
memboot notes-sync --project /path/to/your/project --repo https://github.com/your-org/notes.git

# Get formatted context for an LLM prompt
memboot context "database schema" --project /path/to/your/project --max-tokens 4000

# Smart context pack (local Ollama rerank + structured output)
memboot context "database schema" --project /path/to/your/project --smart-pack --local-only

# Check license status
memboot status

# Rotate DB encryption key
memboot rekey --project /path/to/your/project --new-db-key "new passphrase"

CLI Commands

Free vs Pro

memboot's core is free forever. Pro is a one-time $59 license — perpetual, no subscription, no account. The key validates entirely offline (HMAC checksum, no phone-home), consistent with the rest of the tool: you own it.

Activate Pro: export MEMBOOT_LICENSE=MMBT-XXXX-XXXX-XXXX

How It Works

Project Files ──→ Chunker ──→ Embedder ──→ SQLite Store
                   (AST)      (TF-IDF)     (~/.memboot/)
                                                │
Query Text ─────→ Embedder ──→ Cosine Sim ──→ Results
                                                │
Memories ───────→ Embedder ──→ Store ───────→ Searchable

1. Index — Recursively discover files, chunk by language (Python AST, Markdown headers, etc.), embed with TF-IDF, store in SQLite
2. Query — Embed your query, compute cosine similarity against all chunks and memories, return top-K
3. Remember — Store episodic memories (decisions, patterns, observations) with embeddings for later retrieval
4. Context — Build token-budgeted markdown blocks with source attribution for LLM consumption

Each project gets its own SQLite database at ~/.memboot/{hash}.db. No servers, no API keys, no network calls.

Security Hardening

• Set MEMBOOT_DB_KEY to enable SQLCipher encryption at rest for the local project DB.
• Set MEMBOOT_NOTES_KEY to encrypt mirrored notes content before committing to notes repos.
• Set MEMBOOT_DB_KEY_NEW and run memboot rekey to rotate DB keys.

How It's Different

Architecture

src/memboot/
├── models.py        # Pydantic v2 data models
├── store.py         # SQLite WAL backend (numpy BLOB serialization)
├── chunker.py       # Language-aware chunking (Python/MD/YAML/JSON/window)
├── embedder.py      # TF-IDF (built-in) + sentence-transformers (optional)
├── indexer.py       # Discovery → chunk → embed → store pipeline
├── query.py         # Cosine similarity search
├── memory.py        # Episodic memory CRUD
├── context.py       # Token-budgeted context builder
├── licensing.py     # Free/Pro tier management
├── cli.py           # Typer CLI commands
├── mcp_server.py    # MCP stdio server (3 tools)
├── notes_repo.py    # Git-backed notes sync/mirror support
└── ingest/          # External file/PDF/web ingestion

Community

Discord — Join the community

License

MIT