Getting started

1. Install

One crate installs both the server and the MCP bridge.

cargo install taguru        # `taguru` (server) and `taguru-mcp` (MCP bridge)

# from source
git clone https://github.com/t0k0sh1/taguru && cd taguru
cargo run --release

# Docker (linux/amd64 + linux/arm64)
docker run -d --name taguru \
  -p 127.0.0.1:8248:8248 \
  -v taguru-data:/data \
  ghcr.io/t0k0sh1/taguru:latest

2. Run and configure

Defaults: 127.0.0.1:8248 ("TAGU" on a phone keypad, chosen to avoid the default ports of likely neighbours) with data in ./data. All configuration is environment variables, and taguru --help lists every one of them.

taguru                       # run as-is
taguru --config taguru.env   # read KEY=VALUE lines from a file —
                             # the exact dialect `docker run --env-file` accepts, so one file drives both.
                             # Real environment variables win over the file; unknown TAGURU_* keys are flagged as probable typos
taguru version

Key environment variables

Observability (RUST_LOG, TAGURU_LOG_FORMAT=json, OTEL_EXPORTER_OTLP_ENDPOINT, search logging via TAGURU_LOG_SEARCHES) and the caps (TAGURU_MAX_BODY_BYTES and friends) are covered in Internal architecture. The full list is taguru --help. OTEL_EXPORTER_OTLP_ENDPOINT turns on the composed retrieval span tree specifically — see Tracing.

3. The first memory

Create a context, store an association, pull the thread. One round trip over plain HTTP.

curl -X PUT localhost:8248/contexts/sake -H 'Content-Type: application/json' \
  -d '{"description":"青嶺酒造という架空の酒蔵の知識"}'

curl -X POST localhost:8248/contexts/sake/associations -H 'Content-Type: application/json' \
  -d '[{"subject":"青嶺酒造","label":"代表銘柄","object":"青嶺","weight":1.0,"source":"第1段落"}]'

curl -X POST localhost:8248/contexts/sake/activate -H 'Content-Type: application/json' \
  -d '{"origins":["青嶺酒造"]}'

The activate response is a list of associations ordered by strength, each row carrying strength (ranking within this call), path (how it was reached), and the attributions of its sources. The full endpoint list and the playbook are distributed as-is by the running server at GET /protocol.

The one-fact request above is only the smallest example. In an ingest loop, collect one document's facts and send them in one /associations request (up to 10,000 associations): every request pays for a durable write and stalls that context's readers while its fsync lands, making single-fact calls roughly two orders of magnitude more expensive per association than batches. More concurrency does not help one context — its writes serialize by design — though different contexts write in parallel. For a corpus or migration, use POST /import on a running server or taguru import offline instead.

4. Running under Docker

The published image is the server alone on scratch — no shell, no libc, nothing to patch, ~13 MB.

• Inside a container, bind 0.0.0.0:8248 (loopback would be unreachable from outside -p). That means no-auth mode reaches as far as you publish it — keep -p on 127.0.0.1, or set TAGURU_API_TOKEN.
• Configuration is the same environment variables (-e, or --env-file taguru.env — the very file --config reads).
• The process runs as uid 65532. A named volume inherits ownership automatically on first use; a bind mount needs chown -R 65532 first (or --user "$(id -u)").
• Runs with --read-only (/data is the only write target). docker stop is a graceful shutdown (flush + usage-stats sweep).
• The HEALTHCHECK is taguru health — the binary probes itself (there is no curl on scratch).

# verifying a backup needs no local toolchain either
docker run --rm -v taguru-data:/data ghcr.io/t0k0sh1/taguru inspect /data

For running as a service, see Docker Compose (a single host), Kubernetes (the probe wiring and single-attachment storage), or — per cloud — the AWS guide, the Azure guide, and the Google Cloud guide. One thing a tag alone can't tell you: latest never re-pulls itself, so confirming what's actually running — and updating it — is covered in Troubleshooting — the image you think you're running.

5. Loading in bulk — taguru import

Initial loads and migrations skip HTTP. JSONL batch files apply straight to the data directory through the same WAL-staged write path the server uses.

taguru import batches/            # every *.jsonl underneath, in name order
taguru import --dry-run batches/  # validate and report only; writes nothing

The only rule is one file = one source's complete truth. Applying a file means "retract that source, then apply the file" — so:

• Idempotent: importing the same file twice lands in the same state. Weights never double-count.
• Revisable: a corrected file replaces the old facts wholesale (the same diff-sync an agent performs live).
• Retryable: a file that failed midway is fixed and re-imported — the retraction is what makes the retry exact.

# a batch file: header first, then one operation per line
{"taguru_batch": 1, "context": "sake", "source": "docs/aomine.md", "create": {"description": "酒蔵の知識"}}
{"passage": "青嶺酒造は1907年創業。杜氏は高瀬。"}
{"paragraph": 0, "section": "沿革"}
{"paragraph": 0, "question": "青嶺酒造の酒造りの責任者は誰?"}
{"subject": "青嶺酒造", "label": "杜氏", "object": "高瀬", "weight": 2.0}
{"alias": "Aomine Brewery", "canonical": "青嶺酒造", "kind": "concept"}

Validation is a separate pass from apply: one malformed line refuses the whole file with its line number, and nothing is written. A running server takes the same contract at POST /import (one request = one batch file) — that is the bulk entrance with no downtime window.

# -d strips newlines, and newlines are the format — use --data-binary
curl -X POST localhost:8248/import -H 'Authorization: Bearer <key>' \
  --data-binary @docs-aomine.jsonl

The complete contract — full semantics of every line type, the table of caps, the concurrency rules — is in the batch import reference.

Producing batch files from documents — taguru extract

taguru extract is an offline producer: it has an OpenAI-compatible chat model read .md/.txt files, decompose them into associations under the /protocol discipline, and writes one batch file per document. The server still never holds model credentials — TAGURU_EXTRACT_* lives only in the extraction process's environment.

TAGURU_EXTRACT_URL=https://api.openai.com/v1/chat/completions \
TAGURU_EXTRACT_MODEL=gpt-4.1 TAGURU_EXTRACT_API_KEY=$KEY \
taguru extract --context sake --description "酒蔵の知識" --out batches/ docs/
taguru import batches/

• The manifest in --out records "content × model × prompt version × context" and skips unchanged documents (--force overrides). A nightly extract→import run pays model calls only for what changed.
• --questions N is doc2query: up to N retrieval questions per paragraph ride along. Their terms index into the paragraph's BM25 postings on every server, and a server with TAGURU_EMBED_PASSAGES also embeds them next to their paragraphs — either way, question-shaped searches land on answer-shaped text.
• Model output is not trusted; the contract is enforced on this side of the wire — invalid items are dropped and counted, and every file is re-validated with the import parser before it is written. Extract cannot produce a file import would reject.
• Running against a local model (Ollama etc.): thinking mode OFF (reasoning tokens devour the time budget), a real context window (num_ctx 16384 — leaving 4k silently truncates and only quality drops), a timeout matched to the hardware via TAGURU_EXTRACT_TIMEOUT_SECS, and --force after re-pointing a serving alias — the manifest trusts the model name.

What the prompt asks and what is enforced, chunking, manifest details, the trust model, and measured quality per model class are in the document extraction reference. For a corpus large enough that one run spans hours or several short-lived instances, see long-running ingestion: bounded run windows, interrupt and resume, and torn-import recovery.

6. Wiring up an LLM agent — MCP

Decomposing and recomposing is the agent's job. The discipline ships automatically with the tool definitions and the MCP instructions (the full text of /protocol), so a connected LLM knows the correct procedure from the start.

Local (stdio bridge)

claude mcp add taguru -e TAGURU_URL=http://127.0.0.1:8248 -- taguru-mcp

That alone makes "ingest the documents in this folder into the sake context" and "tell me about 青嶺酒造, with sources" work as the loop of directory pick → resolve → describe/query/activate → citation. A real round trip is traced in the walkthrough.

Remote (Streamable HTTP)

claude mcp add --transport http taguru https://your-host/mcp \
  --header "Authorization: Bearer $TAGURU_API_TOKEN"
# Claude API: mcp_servers = [{type: "url", url: "https://your-host/mcp",
#                             name: "taguru", authorization_token: "…"}]

POST /mcp speaks the MCP Streamable HTTP transport (stateless profile: plain JSON responses, no session to manage) behind the same Bearer token as the rest of the API.

claude.ai custom connectors (OAuth)

For clients that cannot attach a header: set TAGURU_PUBLIC_URL, point the connector at https://your-host/mcp, and paste an existing API key on the consent page — from then on that connection acts as that key (key@client in the access logs). Discovery, dynamic registration, and PKCE are built in; no external IdP is needed. The OAuth token opens /mcp only; the plain API stays key-only.

Leaving localhost requires TLS (via a reverse proxy). The token is the whole credential — whoever holds it holds the memory. Cut a named key per client (TAGURU_API_TOKENS) so a leak costs one revocation.

7. Operational basics

• Health: GET /health answers 200 with {"status": "ok", "version": "…"} while healthy, and 503 when the write path is unhealthy or a maintenance sweep is active. Once the disk recovers, it self-heals within one flush interval.
• Metrics: GET /metrics (Prometheus text). Per-route latency, cache/flush/WAL/embedding outcomes, search hits and misses, a breakdown of 500 causes. Context names are deliberately kept out of the labels (clients mint names, so series would grow without bound) — per-context numbers live in the usage stats of GET /contexts.
• Backups: one context = one file family (.ctx .meta.json .passages.bin .passages.wal.jsonl .bm25.bin .vectors.bin .wal.jsonl; group records ride beside them as {name}.group). Always as a set. The simplest way to have one continuously: set TAGURU_REPLICATE_URL and the server ships every family (both log lanes tailed, published files whole) to object storage with seconds of lag — recover with taguru restore --out DIR, then taguru inspect DIR; or start a server on an empty directory with the same URL and it boots from the bucket directly (while the previous writer still looks alive, that boot asks for --take-over first). For point-in-time copies: every writer is fsync+rename, so filesystem snapshots (ZFS/Btrfs/LVM) are safe at any instant. A naive rsync/cp against a live server does not guarantee cross-file consistency — stop the server, take a real snapshot, or replicate. POST /flush writes out everything dirty right before. Verify with taguru inspect /path/to/data (the same fully-validating load + WAL replay the server does; non-zero exit = corruption of acknowledged data).
• Exclusivity: one process per data directory at a time (serve or import). The lock is advisory (flock-style — dependable on local disks, but NFS/EFS/FUSE may grant it to both sides). In a rolling deploy the new process correctly bows out while the old one lives — on a shared volume, deploy stop-then-start (strategy: Recreate on Kubernetes).
• When something is slow, stuck, or the wrong shape: the troubleshooting guide attributes the symptom to a layer — version skew, a stale image, Taguru's own latency vs. the LLM's, the semantic lane's silent degrade — before anything gets reset.