kraang 0.2.1
A second brain for humans and their agents — MCP server backed by SQLite FTS5.
Requires Python: >=3.10
Keywords: fts5, knowledge-management, mcp, second-brain, sqlite

<table>
  <tr>
    <td><img src="assets/kraang.jpeg" alt="Kraang" width="350"></td>
    <td><h1>Kraang</h1><b>A second brain for you and your agents.</b></td>
  </tr>
</table>

Kraang is an MCP (Model Context Protocol) server that gives AI assistants persistent memory and session indexing, backed by SQLite with FTS5 full-text search. It stores knowledge notes, indexes conversation transcripts, and surfaces what matters via search.

## Why?

AI assistants forget everything between sessions. Kraang gives them persistent memory — decisions, debugging breakthroughs, patterns — so your next conversation picks up where the last one left off.

## Quick Start

The fastest way to get started is with `kraang init`:

```bash
uvx kraang init        # ephemeral — downloads on each run
uv tool install kraang # persistent — install once, use everywhere
kraang init
```

This creates a `.kraang/` directory, initializes the database, configures `.mcp.json`, sets up a `SessionEnd` hook for automatic session indexing, creates `.claude/rules/kraang.md` for proactive agent behavior, and indexes any existing sessions.

### Manual Configuration

Add to your MCP client configuration (e.g. Claude Code, Claude Desktop):

```json
{
  "mcpServers": {
    "kraang": {
      "command": "uvx",
      "args": ["kraang", "serve"],
      "env": { "KRAANG_DB_PATH": ".kraang/kraang.db" }
    }
  }
}
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `remember` | Save knowledge to the brain. If a note with the same title exists, it updates in place. |
| `recall` | Search notes and indexed sessions. Supports scoping to `"notes"`, `"sessions"`, or `"all"`. |
| `read_session` | Load a full conversation transcript by session ID (use `recall` to find sessions first). |
| `forget` | Downweight or hide a note by adjusting its relevance score (0.0 = hidden, 1.0 = full). |
| `status` | Get a knowledge base overview: note/session counts, recent activity, top tags. |

## CLI Commands

| Command | Description |
|---------|-------------|
| `kraang init` | Set up kraang for the current project (database, config, hooks, initial index). |
| `kraang serve` | Run the MCP server over stdio (invoked by Claude Code). |
| `kraang index` | Index or re-index conversation sessions for the project. |
| `kraang sessions` | List recent conversation sessions. |
| `kraang session <id>` | View a session transcript in detail. |
| `kraang search <query>` | Search notes and sessions from the terminal. |
| `kraang notes` | List notes in the knowledge base. |
| `kraang status` | Show knowledge base health and statistics. |

## Architecture

Kraang uses a layered architecture:

1. **Models** (`models.py`) -- Pydantic schemas for notes, sessions, and search results.
2. **Store** (`store.py`) -- SQLite backend with FTS5 full-text search and BM25 ranking.
3. **Search** (`search.py`) -- Query parsing and FTS5 expression building.
4. **Indexer** (`indexer.py`) -- Reads Claude Code JSONL transcripts and indexes sessions.
5. **Server** (`server.py`) -- MCP server exposing 5 tools over stdio.
6. **CLI** (`cli.py`) -- Typer CLI for init, serve, index, and local queries.
7. **Formatter** (`formatter.py`) -- Markdown formatting for tool and CLI output.
8. **Display** (`display.py`) -- Rich console rendering for CLI commands.
9. **Config** (`config.py`) -- Project root detection and database path resolution.

## Development

```bash
git clone https://github.com/johnnygreco/kraang.git && cd kraang
uv sync --extra dev
make install-hooks   # install pre-commit hooks (run once)
make test
make lint
```

Pre-commit hooks run automatically before each commit (ruff format, ruff check --fix, ty). Run manually:

```bash
uv run pre-commit run --all-files
```

Run the full check suite:

```bash
make coverage   # tests + coverage report
make format     # auto-format with ruff
```

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Kraang tools not showing up in Claude Code | Restart Claude Code after running `kraang init` |
| Sessions not being indexed automatically | Check that `.claude/settings.json` has the `SessionEnd` hook |
| Search returns nothing | Run `kraang status` to check counts, then `kraang index` to re-index |
| Need a fresh start | Delete `.kraang/` and re-run `kraang init` |

## License

Apache 2.0