IOBOXX
DOCS · QUICKSTART

Quickstart

Clone, build, point Claude Code at it. Under ten minutes from `git clone` to a working agent memory.

ioboxx-core is a Rust knowledge graph engine that serves itself as an MCP server. Persistent typed memory for AI agents, running on your machine — nothing sent to the cloud. Dual licensed: AGPL plus commercial.

Three steps. The whole thing should take less than ten minutes once Rust is on your machine.

STEP 1Build

Clone the repo and build a release binary. Rust 1.93+ is required and is pinned in rust-toolchain.toml — rustup installs the correct toolchain automatically.

git clone https://github.com/ioboxx/ioboxx-core.git
cd ioboxx-core
cargo build --release

STEP 2Run

Zero-config. From inside any Obsidian vault, point cargo at the manifest and ioboxx-core auto-detects .obsidian/ and starts serving.

cd /path/to/your/obsidian-vault
cargo run --manifest-path /path/to/ioboxx-core/Cargo.toml

For non-Claude-Code MCP clients, run in HTTP mode. The MCP endpoint is at http://localhost:3002/mcp; a health check is at http://localhost:3002/health.

cargo run -- --vault-path ./my-vault --port 3002

STEP 3Connect Claude Code

Add to your project’s .mcp.json. Claude Code starts the server on session open and shuts it down on session close — no background processes to manage.

{
  "mcpServers": {
    "ioboxx-local": {
      "command": "cargo",
      "args": [
        "run", "--release",
        "--manifest-path", "/path/to/ioboxx-core/Cargo.toml",
        "--", "--vault-path", "/path/to/your/vault",
        "--stdio", "--no-watch"
      ]
    }
  }
}

After Claude Code reloads, your agent has 24 MCP tools available across discovery, read, write, semantic, and memory categories:

ping, get_summary, get_schema, get_object, list_objects, search_objects, search_indexed, create_object, set_attributes, delete_object, delete_attribute, traverse_references, semantic_search, find_similar, load_relevant_context, get_relevance, curate_memory, get_activity_summary — plus a few more in the latest build.

The full tool reference lives at /docs/mcp.

VAULTMinimum vault format

ioboxx-core reads Obsidian markdown with YAML frontmatter. Required keys: type and title. Optional but recommended: tags, created, status, and related with wikilinks (each wikilink becomes a typed graph edge).

---
type: concept
title: Knowledge Graph
tags: [graph, data-structure]
created: 2026-04-12
status: developing
related:
  - "[[vector-search]]"
---

# Knowledge Graph

Your content here. All [[wikilinks]] become graph edges automatically.

Supported types: concept, entity, source, comparison, question, decision, meta.

RUNTIMEWhat lives in .ioboxx/

Everything ioboxx-core needs to recover state lives under .ioboxx/ next to your vault. After cold start the vault is never read again — the runtime directory alone is enough for full recovery.

PathPurposeSafe to delete?
commitlogAppend-only mutation log, fsynced per entry. System of truth.Only with snapshot — forces cold rebuild from the vault.
snapshot.binBinary graph checkpoint (bincode). Primary recovery path on start.Yes — rebuilt from commitlog on next start.
snapshot.jsonJSON checkpoint. Fallback when bincode fails.Yes.
vectors.binPersisted vector index. Skips re-embedding on restart.Yes — recomputed from graph on next start.
fastembed_cache/ONNX model cache for the local embedder (~87 MB on first download).Yes — re-downloaded on next start with embeddings enabled.

More on what is actually serving these tools at /docs/architecture/memory.

FLAGSUseful runtime flags

  • --no-embeddings — skip the embedder. Faster startup, no semantic search.
  • --no-watch — don’t watch the vault for file changes.
  • --hmac-key <hex> — sign commitlog entries for tamper detection.
  • --backup <dir> and --restore <dir> — atomic copy and restore of .ioboxx/.
  • --purge <vault> — delete the runtime directory for a vault. The server must not be running against it.

NEXTWhere to go next

Last updated: 2026-05-16