🎮 asobi

A persistent, project-local knowledge graph CLI for LLM agents.

Keep memory, track session state, and share context across conversations — stored in a local, single-file SQLite database.

---

✨ Features

• Knowledge graph — entities, append-only (capped) observations, and directed relations.
• Truths — durable key→value facts per entity for current state (status, version); status-as-truth makes a board a single search --where status=….
• Fast search — search over SQLite FTS5 (BM25 relevance, porter stemming) with a substring fallback, plus --where key=value truth filters (the query term is optional).
• Concurrency-safe — WAL-mode storage with bounded busy timeouts, so lead and dispatched agents can share a graph.
• Lazy reads — graph/search return truths + counts; show returns the full body. Cheap to load, cheap on tokens.
• Skills — install reusable agent instructions from a git repo or local path.

🏗️ Architecture

One synchronous storage contract, one bundled backend, one local file — see ADR 0001 and ADR 0002 for why.

flowchart LR
    CLI["src/cli/*\n(commands, dispatch, graph, skills)"]
    API["api::v2\nGraphStore · SearchStore · SkillStore\nSnapshotStore · BackupStore · MaintenanceStore · TaskStore"]
    Sqlite["SqliteStore\n(src/storage/sqlite.rs)"]
    DB[("asobi.db\nWAL + FTS5")]

    CLI --> API
    API --> Sqlite
    Sqlite --> DB

Loading

Commands depend only on the api::v2 traits, never on rusqlite types directly — src/storage/sqlite.rs is the only file that owns SQL, schema, and pragmas.

📦 Installation

From crates.io (recommended)

cargo install asobi

Prebuilt binary (cargo-binstall)

No compile — cargo-binstall pulls the binary from the GitHub release:

cargo binstall asobi

From source

cargo install --git https://github.com/azusachino/asobi

Or build locally with make build. Requires Rust 1.85+, Edition 2024.

🚀 Quick Start

asobi 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)
asobi obs "my-project" "Decided to use WAL mode for concurrency"
asobi truth "my-project" "status" "in-progress"
asobi search "WAL"
asobi show "my-project" --with-ids
asobi update-obs "my-project" 1 "Decided to use SQLite WAL for concurrency" --id
asobi rm-obs "my-project" 1 --id

💻 Common Commands

• asobi graph / search <q> / search --where status=READY / show <name>... --expand part_of --with-ids — read the graph (supports subtree expansions and sequential observation IDs).
• asobi new <name> <type> --obs "..." / obs <name> "..." / update-obs <name> <old/id> <new> [--id] / rm-obs <name> <content/id> [--id] — manage observations (supports updates and deletions by unique sequential IDs).
• asobi truth <name> <key> <value> / rm-truth <name> <key> / history <name> [key] — manage truths and read their change history (overwrites are archived with valid-time; history is opt-in and never shown in graph/search/show).
• asobi skills install <src> --all / update / skills / skills show <name> — manage skills (--all and update sync, pruning skills dropped upstream; --select is additive).
• asobi stats / export -o graph.json / import graph.json / reset — inspect & manage.
• asobi backup / restore <snapshot> [--force] — full-fidelity SQLite backups; see the usage guide.

🔒 Sandboxed Environments

When running in sandboxed or restricted environments (such as Codex, Nix build sandboxes, or containerized runners), use a project-local workspace (asobi init --local) or configure custom database paths (ASOBI_HOME, ASOBI_DATABASE_URL). The storage backend manages WAL coordination and retry behavior; legacy journal-mode and busy-timeout overrides are not supported.

See the Running in Sandboxed Environments section in the Usage Guide for more details.

🛠️ Development

• Task runner: make (Nix-wrapped). make check is the quality gate: rustfmt, Prettier, Ruff, Clippy with -D warnings, Rust tests, storage-boundary checks, and CLI verification.
• Rust quality standard: keep code rustfmt-clean, introduce no Clippy warnings, preserve single-threaded test isolation, and add regression coverage for behavior changes. Run make check before commits.
• Coverage: with cargo-tarpaulin installed, run cargo tarpaulin --out Html --output-dir coverage and open coverage/index.html.
• Benchmarks: run make bench; use performance profiling for Criterion baselines, DHAT allocations, and SQL plans.
• See docs/usage.md for the full CLI reference, docs/workflow.md for the day-to-day and task dispatcher workflow, and docs/architecture.md for design.