Get started

From nothing to a
searchable memory.

Five steps. One dependency. No database server, no vector service, and no model to download.

01 / Install

Install the package.

Python 3.11 or newer. The base install pulls in exactly one runtime dependency, mcp. SQLite and its FTS5 extension come with Python.

pip install hadano-ai-cabinet

Check that the module resolves before going further. If this prints a JSON object, the install is good.

python -c "import hadano; print(hadano.__all__)"

02 / Register

Tell your AI client about it.

Hadano speaks MCP over stdio. Add this to your client's MCP configuration. Nothing listens on a port, and nothing starts until your client launches it.

{
  "mcpServers": {
    "hadano": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "hadano.server"],
      "env": { "HADANO_DB": "~/hadano.db" }
    }
  }
}

Where that file lives

client	configuration
Claude Code	`claude mcp add`, or the `mcpServers` block in your settings
Claude Desktop	`claude_desktop_config.json`
Cursor	`.cursor/mcp.json`
anything else	whatever that client calls its MCP server list

The database file is created on first use. Point HADANO_DB anywhere you like — if you leave it out, the file is hadano.db in the working directory, which is rarely what you want.

03 / Store

Put something in it.

Ask your assistant to save something. It calls store_document for you — there is no separate command to learn.

# what you say
Save my deployment runbook to Hadano, tagged ops.

# what the client sends
store_document(
  title    = "Deployment runbook",
  content  = "...",
  tags     = ["ops"]
)

# what comes back
{ "id": "8abacdf04d1a49b28f84347cb1d94180",
  "chunks": 2,
  "sha256": "aea22d7f...",
  "request_id": "4f1c..." }

The document is split into overlapping chunks of 800 codepoints, indexed for full-text search, and hashed. The split is deterministic: the same text always produces the same chunks. Every call also returns a request ID and lands in the audit log.

04 / Search

Find it again.

Search runs in two stages, and the first one is enough most of the time. search_documents is keyword matching over FTS5 with BM25 ranking — deterministic, and it works on Japanese and other CJK text without a morphological analyzer.

# stage 1 — find the document
search_documents(query = "rollback", top_k = 5)

{ "documents": [
    { "doc_id": "8abacdf0...",
      "title": "Deployment runbook",
      "score": 0.0325,
      "matched_chunks": [
        { "chunk_id": 2, "seq": 1, "text": "..." } ] } ] }

If you want more than the matching document — things connected to it — take up to three chunk_id values from stage 1 and pass them as seeds to stage 2. That cap is deliberate. It is what keeps cost bounded and keeps every result traceable to a source document.

# stage 2 — expand from what stage 1 actually matched
search_knowledge(seed_chunk_ids = [2], top_k = 10)

{ "related_chunks": [],
  "related_edges": [
    { "src": "runbook", "rel": "cites",
      "dst": "rollback-policy", "source": "graph" } ],
  "truncated": false }

05 / Keep a copy

It is one file. Copy it.

The whole knowledge base is hadano.db. Moving it to another machine is a file copy. For a snapshot that is safe to take while the database is in use, or for a format you can read without SQLite, use the two commands below.

# consistent snapshot, safe during writes
python -m hadano.backup --db ~/hadano.db --out ~/backups/

# everything as JSONL, one document per line
python -m hadano.dump --db ~/hadano.db --out cabinet.jsonl

# and back into an empty file
python -m hadano.dump --restore --db ~/new.db --in cabinet.jsonl

Restore replaces documents with the same ID and leaves everything else alone, so running it twice changes nothing the second time. It does not delete documents that are missing from the dump — a dump is a state, not a history, so it is right for backup and migration and wrong as a two-way sync.

Next

Where to go from here.

you want	go to
Every tool, parameter, limit, and error code	the manual
Why search works in two stages	mechanism
Whether this fits your case at all	where this fits
Measured latency and memory	measured

From nothing to asearchable memory.