Getting Started

Last updated 2026-10-21

Build the kura binary, register a database, start the daemon, and run a first keyword search against files you drop in.

Requirements

Item	Requirement	Why
Operating system	macOS (APFS/HFS+) or Linux (ext4/xfs)	The daemon detaches with `setsid` and the watcher relies on POSIX file metadata
Go	1.25.1 or later	`go.mod` declares `go 1.25.1`
C toolchain	Any compiler cgo can use	SQLite is accessed through `github.com/mattn/go-sqlite3`
`pdftotext`	Only for PDF files (poppler-utils)	PDF text is extracted with `pdftotext -layout -enc UTF-8`

Build and Install

git clone https://github.com/pardnchiu/KuraDB.git
cd KuraDB
make build

Target	Runs
`make build`	`go build -o bin/kura ./cmd/app`
`make app`	Stop a running daemon, build, move the binary to /usr/local/bin/kura with `sudo`, start the daemon
`make stop`	`go run ./cmd/app stop`
`make test`	`go test -v -count=1 ./...`
`make add <name>`, `make list`, `make remove <name>`, `make edit <old> <new>`, `make port <args>`, `make help`	The matching subcommand through `go run ./cmd/app`

Register a Database and Start the Daemon

kura add notes
kura

kura add notes creates ~/.config/kuradb/notes/inbox/, links it as ~/Kura_notes, and records the name in db.json. Running kura with no arguments forks the daemon into the background and prints its address, for example http://localhost:21182.
A database added while the daemon is running is not picked up until the daemon restarts:

kura stop
kura

Drop Files and Search

cp ~/Documents/design-notes.md ~/Kura_notes/
curl "$(cat ~/.config/kuradb/endpoint)/api/search?db=notes&q=sqlite"

The watcher scans each inbox every 10 seconds, so a new file is searchable within about 10 seconds. The response groups matching paragraphs by source file:

{
  "keyword": [
    {
      "source": "/Users/you/.config/kuradb/notes/inbox/design-notes.md",
      "matches": [
        { "chunk": 2, "content": "Second paragraph about SQLite" }
      ]
    }
  ]
}

To let an agent query the same data, register the stdio MCP server with your client, for example in Claude Code:

claude mcp add kura -- kura mcp

Next Steps

Indexing Pipeline: how dropped files become searchable rows
Keyword Search: how queries are matched and ranked
MCP Server: list_rag and search_rag for agents
CLI Reference: every kura subcommand