# Miku

Miku is a persistent, project-local knowledge graph CLI for AI agents. Agents use it to keep memory, track session state, and share context across conversations — stored in a local libSQL/SQLite file, no server required.

## Features

- **Knowledge graph** — entities, append-only (capped) observations, and directed relations.
- **Truths** — durable `key→value` facts per entity for current state (`status`, `version`).
- **Fast search** — `search-nodes` over FTS5 (porter stemming + BM25) with a substring fallback.
- **Lazy reads** — `read-graph`/`search-nodes` return truths + counts; `open-nodes` returns the full body. Cheap to load, cheap on tokens.
- **Skills** — install reusable agent instructions from a git repo or local path.
- **MCP server** — `miku mcp` serves the graph over stdio to MCP-aware clients.
- **Document tier** (optional, `--features documents`) — `ingest` + semantic `query` over Markdown.

## Installation

From source (Rust 1.85+, Edition 2024):

```bash
cargo install --git https://github.com/azusachino/miku
```

Build locally with `make build` (graph/MCP CLI) or `make build-documents` (adds `ingest`/`query`/`compact`).

## Quick Start

```bash
miku init                  # one-time setup (XDG); use --local for a project-scoped graph

# Store and recall context (names are hierarchical, e.g. ame:mobile-support:task-1)
miku add-observations "my-project" "Decided to use WAL mode for concurrency"
miku add-truth "my-project" "status" "in-progress"
miku search-nodes "WAL"
miku open-nodes "my-project"
```

## Common Commands

- `miku read-graph` / `search-nodes <q>` / `open-nodes <name>...` — read the graph.
- `miku add-truth <name> <key> <value>` / `delete-truth <name> <key>` — manage truths.
- `miku skills install <src> --all` / `update` / `skills` / `skills show <name>` — manage skills (`--all` and `update` sync, pruning skills dropped upstream; `--select` is additive).
- `miku mcp` — run as an MCP stdio server.
- `miku stats` / `export -o graph.json` / `import graph.json` / `reset` — inspect & manage.

## Development

- **Task runner**: `make` (Nix-wrapped). Run `make check` for fmt + lint + tests.
- See [`docs/usage.md`](docs/usage.md) for the full CLI reference and [`docs/architecture.md`](docs/architecture.md) for design.
