Metadata-Version: 2.4
Name: kraang
Version: 0.1.0
Summary: A second brain for humans and their agents — MCP server backed by SQLite FTS5.
Author: Johnny Greco
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: fts5,knowledge-management,mcp,second-brain,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: coverage>=7.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<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 backed by SQLite with FTS5 full-text search. It stores, searches, and manages knowledge notes so your agent can recall what matters.

## Quick Start

```bash
uv pip install kraang
```

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

```json
{
  "mcpServers": {
    "kraang": {
      "command": "kraang",
      "env": { "KRAANG_DB_PATH": "~/.kraang/brain.db" }
    }
  }
}
```

If `KRAANG_DB_PATH` is not set, it defaults to `~/.kraang/brain.db`.

## Tool Reference

| Tool | Description | Parameters |
|------|-------------|------------|
| `add_note` | Add a new note | `title`, `content`, `tags?`, `category?`, `metadata?` |
| `search_notes` | Full-text search with filters | `query`, `tags?`, `category?`, `status?`, `limit?` |
| `update_note` | Update an existing note | `note_id`, `title?`, `content?`, `tags?`, `category?`, `status?` |
| `delete_note` | Delete a note | `note_id` |
| `list_tags` | List all tags | *(none)* |
| `list_categories` | List all categories | *(none)* |
| `list_notes` | Browse/list notes | `status?`, `limit?`, `offset?` |
| `get_stale_items` | Find notes not updated recently | `days?` |
| `daily_digest` | Activity summary | *(none)* |
| `suggest_related` | Find related notes | `note_id`, `limit?` |

### Prompts

| Prompt | Description |
|--------|-------------|
| `review_stale` | Review stale notes and suggest actions (update/archive/delete) |
| `summarize_kb` | Get a high-level summary of the knowledge base |
| `find_gaps` | Identify underrepresented topics and organization improvements |

## Development

```bash
git clone https://github.com/johnnygreco/kraang.git && cd kraang
uv sync --extra dev
make test
make lint
```

Run the full check suite:

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

## Architecture

Kraang uses a layered architecture:

1. **Models** (`models.py`) -- Pydantic schemas define the data contracts: `Note`, `NoteCreate`, `NoteUpdate`, `SearchQuery`, etc.
2. **Store Protocol** (`store.py`) -- An async `NoteStore` protocol that any storage backend must implement.
3. **SQLite Backend** (`sqlite_store.py`) -- The default implementation using SQLite with FTS5 for full-text search and BM25 ranking.
4. **MCP Server** (`server.py`) -- Exposes the store as MCP tools and resources over stdio, ready for any MCP-compatible client.

## License

Apache 2.0
