akatsuki

Query and mutate a Markdown knowledge vault via CLI and MCP stdio tools.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/fusuyfusuy/dot-agents --skill akatsuki-fusuyfusuy
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: akatsuki
Source: https://github.com/fusuyfusuy/dot-agents/tree/main/skills/akatsuki
Command: npx skills add https://github.com/fusuyfusuy/dot-agents --skill akatsuki-fusuyfusuy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Agents entering a repository lack context about system architecture, live services, port mappings, and past decisions, and have no structured way to record work logs or architectural changes back into a persistent knowledge base. ## Core Features & Use Cases - Hybrid Knowledge Search: Combines BM25 full-text search and dense vector embeddings with Reciprocal Rank Fusion to retrieve notes, with optional 1-hop graph context. - Token-Bounded Reading: Extracts machine-actionable boundary contracts (ports, dependencies, invariants) from notes, cutting 70-90% of narrative token bloat. - Blast Radius & Graph Mapping: Recursively maps upstream dependents and downstream dependencies before mutations, with cycle detection. - Structured Mutations & Telemetry: Surgically updates frontmatter keys, appends sections, writes notes, and logs telegraphic work entries under 140 characters. - Use Case: Before modifying a Docker Swarm service, run a blast-radius analysis on the target, read its boundary contract, apply the change, verify wikilink integrity, and log the outcome to the daily ledger. ## Quick Start Ask the agent to search the akatsuki vault for the current project's service topology and port mappings before making any infrastructure changes.

Frequently Asked Questions about akatsuki

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search a Markdown knowledge base with hybrid search?▼

Use akatsuki search with the default hybrid mode, which fuses BM25 keyword rankings from SQLite FTS5 and dense vector embeddings via Reciprocal Rank Fusion. Add --with-graph to attach 1-hop dependency context to results.

How to reduce token usage when reading notes with an AI agent?▼

Use akatsuki contract to extract only machine-actionable boundaries like ports, dependencies, and invariants, eliminating 70-90% of narrative content. For full notes, akatsuki read supports --section and --budget flags for token-bounded slices.

Does akatsuki work as an MCP server?▼

Yes, running akatsuki mcp starts a JSON-RPC stdio server exposing tools like akatsuki_search, akatsuki_blast, and akatsuki_write_note. Each MCP tool maps directly to an equivalent CLI subcommand.

Can I use akatsuki without the optional embeddings dependencies?▼

Yes, the core is zero-dependency and BM25 search works without extras. The akatsuki[embeddings] extra adds sentence-transformers and torch for vector and hybrid modes, capped at 2 CPU threads with a local ephemeral vectors.db.

Why does akatsuki verify fail with exit code 1?▼

Exit code 1 indicates unresolved wikilinks, schema lint errors, failed invariant assertions, or a missing note. Run akatsuki lint to identify frontmatter schema violations and akatsuki verify to locate broken wikilinks across the vault.