IntentDB

IntentDB is a local-first "causal memory" database for AI coding agents.

It answers one question extremely well:

"Why did this file change?"

It does that by indexing your local AI coding history and linking every file edit to the user prompt (intent) that triggered it, plus a compact diff preview and any nearby agent reasoning.

Highlights

• Causal attribution: link file edits to the prompt that caused them
• Fast "why" lookups: LMDB hot cache for file history
• Keyword search: SQLite FTS over prompts, diffs, and reasoning
• Agent-native: MCP tools so other agents can query the history for you
• Optional semantic search: embeddings + sqlite-vec

Documentation quick links

• Quick start
• Use cases
• Highlights
• What it indexes
• How it works
• Installation
• Usage
• Releasing
• Configuration
• Privacy

Quick start

Prereqs: Python (see pyproject.toml) and uv.

uv sync
uv run intentdb etl

uv run intentdb why path/to/file.py
uv run intentdb search "grpc timeout"
uv run intentdb session <session-uuid-prefix>
uv run intentdb context <change-uuid>
uv run intentdb info

Example output (abridged):

$ intentdb why src/worker/auth.py

  1  Feb 03 12:44  Edit  [claude]  session 9c12a3...
     File: src/worker/auth.py
     User said: "Fix token refresh loop"
     Agent reasoning:
       ...
     Diff:
       @@ ...
       + ...

Demo

Use cases

• Debug regressions: trace a surprising edit back to the prompt that caused it
• Code review archaeology: understand the "why" behind a diff days later
• Onboarding: learn how a codebase changed by reading intent + reasoning
• Agent coordination: let other agents query your local history via MCP
• Audit trail / provenance: answer "who/what changed this" across multiple agent sources

What it indexes

IntentDB reads from local, on-disk histories (no server required):

• Claude Code session JSONL (default: ~/.claude/projects/**/*.jsonl)
• Codex CLI threads (default: ~/.codex/state_5.sqlite)
• Cursor Composer chats (default: ~/Library/Application Support/Cursor/.../state.vscdb)
• Optional real-time tool-use queue (hook_queue.jsonl) via a Claude Code hook

It stores data locally under ~/.claude/intent-db (configurable):

• intent.db (SQLite): durable history + FTS keyword search
• hot.lmdb (LMDB): hot cache for fast "why" lookups by file path
• vec_changes (sqlite-vec, optional): semantic search

Why it exists

When you work with AI agents, the real "why" often lives in chat transcripts:

• tool calls happen across many turns
• the user intent can be several parent messages back
• a file can be touched by multiple agents (Claude Code, Codex, Cursor)
• a week later, "why did we do this" becomes expensive to reconstruct

IntentDB makes that reconstruction a query.

How it works

At a high level:

1. Parse session histories and extract messages + tool-use events.
2. For each file-touching tool call, walk the parent chain to find the nearest real user prompt (skipping tool-result user turns).
3. Store the change record (intent, reasoning, diff preview) in SQLite and a hot index in LMDB.

Sources (local)
  - ~/.claude/projects/**/*.jsonl
  - ~/.codex/state_5.sqlite
  - Cursor state.vscdb
  - hook_queue.jsonl
        |
        v
ETL / indexer
  - extract messages
  - resolve "user intent"
  - build diff preview
        |
        +--------------------------+
        |                          |
        v                          v
SQLite (intent.db)                 LMDB (hot.lmdb)
  - messages                        - c:<change_uuid>
  - changes                         - f:<file_path> -> history
  - search_index (FTS5)             - s:<session_uuid>
  - vec_changes (optional)
        |
        v
CLI + MCP server + daemon

For deeper details: docs/ARCHITECTURE.md.

Installation

From PyPI

python -m pip install intentdb
intentdb etl

If you prefer uv:

uv tool install intentdb
intentdb etl

From source (recommended for now)

git clone https://github.com/H4RR1SON/intentdb.git
cd intentdb

uv sync
uv run intentdb etl

Claude Code integration (macOS)

install.sh is macOS-focused (launchd). It will modify local config files.

bash install.sh

What it does:

• creates .venv and installs deps
• registers a Claude Code PostToolUse hook in ~/.claude/settings.json
• registers the MCP server in ~/.mcp.json
• runs an initial intentdb etl
• installs and starts a daemon that keeps indexing

Optional: semantic search (embeddings)

Semantic search requires optional dependencies and an embedding provider key.

uv sync --extra semantic
export VOYAGE_API_KEY="..."
uv run intentdb embed

Usage

Common commands:

• intentdb etl - index all known sources (Claude Code, Codex, Cursor)
• intentdb why <file> - show changes to a file, with the triggering prompt
• intentdb search <query> - keyword search across prompts, diffs, reasoning
• intentdb session <uuid> - list all changes in a session (prefix ok)
• intentdb context <change-uuid> - show surrounding conversation
• intentdb info - stats and per-agent breakdown

MCP server:

uv run intentdb-mcp

Releasing

IntentDB uses a tag-based release workflow.

# 1) bump version in pyproject.toml (and optionally CHANGELOG.md)
git commit -am "Release vX.Y.Z"

# 2) tag + push
git tag vX.Y.Z
git push origin main --tags

GitHub Actions will:

• build sdist/wheel
• publish to PyPI (trusted publishing via OIDC)
• create a GitHub Release with artifacts

Social preview

This repo includes a share image you can upload as the GitHub social preview:

• assets/social-preview.svg

GitHub requires a raster image for the social preview in Settings; export the SVG to PNG (1280x640) and upload it in:

Settings -> Social preview

Configuration

Environment variables (optional):

• INTENTDB_DIR: where to store intent.db, hot.lmdb, state files
• INTENTDB_PROJECTS_DIR: where to read Claude Code session JSONL files
• CLAUDE_DIR: base directory for Claude Code data (default: ~/.claude)

Privacy

IntentDB stores your prompts, diffs, and agent reasoning locally.

If you enable semantic search / embeddings, text is sent to the embedding provider. Details: docs/PRIVACY.md.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.