🌅 Akatsuki (暁)

High-Performance Native Rust CLI and Model Context Protocol (MCP) Knowledge Secretariat for Living System Memory, Architectural Contracts, and Multi-Agent Orchestration.

🏛️ What is Akatsuki?

As AI coding swarms and autonomous agents (Antigravity, Claude Code, pi, OpenCode, Cursor) write and refactor code, traditional static documentation decays. Infrastructure configurations drift, network ports clash, and architectural boundaries get silently breached.

Akatsuki solves this by providing a Living Systems Memory Substrate:

• Dual-Layer Architecture: Pure Markdown Git repository as the immutable source of truth paired with an ephemeral, high-speed SQLite WAL projection (.akatsuki/cache.db) synced via parallel Blake3 content hashing (Rayon).

• Machine-Verifiable Contracts: Inspect living system contracts, service boundaries, and cluster topology (akatsuki contract <note>) using 70–90% fewer tokens than raw document reads.

• Living Invariant Testing (bash:verify): Execute machine-verifiable infrastructure assertions (ports, containers, daemons) embedded in Markdown notes with process group isolation, execution timeouts, and security sanitization.

• Hybrid Search (BM25 + Semantic Vectors): Fuses SQLite FTS5 Okapi BM25 with pure-Rust Candle embeddings (intfloat/multilingual-e5-small, 384D) via Reciprocal Rank Fusion (RRF, $k=60$).

• Native Dual-Interface (CLI + MCP): Operate seamlessly from the human terminal (akatsuki <command>) or equip autonomous agents directly through native JSON-RPC 2.0 stdio (akatsuki mcp).

• Resilient MCP Engine: 20 specialized architectural tools with panic isolation (catch_unwind), type coercion (arg_bool, arg_usize), and parameter aliasing.

Related MCP server: cog-brain

🚀 Quick Start

1. Installation

Option A: Standard Installation (Pure Lexical BM25, Zero ML Overhead) Compiles with native SQLite FTS5 lexical ranking, instant sub-millisecond startup:

cargo install --path .

Option B: With Semantic Vector Embeddings & Hybrid RRF Search Compiles with the pure-Rust Candle tensor engine for local offline semantic embeddings:

# Build and install with vector features
cargo install --path . --features vectors

# Download the multilingual-e5-small model weights into ~/.cache/akatsuki/models/
akatsuki setup-models

2. Living Memory Vault Structure

Akatsuki operates on structured knowledge vaults:

knowledge-base/
├── .akatsuki/          # Derived SQLite projection and locks (gitignored, auto-rebuilt)
├── .gitignore          # Multi-machine ignore rules
├── AGENTS.md           # Master architectural protocol and invariants
├── INDEX.md            # Auto-maintained catalog and domain index
├── 01-Daily/           # Daily activity ledgers & worklogs
├── 20-Projects/        # Active software project architectures
├── 40-Systems/         # Host specifications, topologies & ADRs
└── _templates/         # Note, system, and daily templates

3. Basic CLI Commands

# Hybrid Search (Okapi BM25 + Dense Semantic Vectors via RRF, k=60)
akatsuki search "docker swarm routing" --mode hybrid --with-graph

# Pure lexical BM25 search
akatsuki search "docker swarm routing" --mode bm25

# Pure semantic vector search (errors explicitly if weights are absent)
akatsuki search "hardware specifications of primary host" --mode vector

# Machine boundary contract extraction (ports, invariants, relations, dependents)
akatsuki contract 40-Systems/Cluster-Topology.md

# Token-budgeted surgical note read
akatsuki read "Cluster-Topology" --section "Private Network Routing" --budget 500

# Graph traversal and dependency blast radius
akatsuki map auth-service --depth 2 --direction both
akatsuki blast auth-service

# Run living invariant checks across system documentation
akatsuki test

# Record an outbound telegraphic caveman ledger entry (<= 280 chars)
akatsuki log --project "web" --summary "migrate edge certs -> renew wildcard SAN; exit 0"

# Surgically update frontmatter without corrupting note bodies
akatsuki set "20-Projects/filament" --key status --value "live"

# Verify vault integrity (wikilinks, orphans, MOC reachability) and lint YAML
akatsuki verify
akatsuki lint

# Synchronize SQLite projection with vault disk state
akatsuki reconcile

🤖 MCP Server Setup (for AI Agents)

Akatsuki runs as a native stdio Model Context Protocol (MCP) server exposing 20 specialized architectural tools:

akatsuki mcp [--vault <dir>]

Configuration Snippets

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "akatsuki": {
      "command": "akatsuki",
      "args": ["mcp"],
      "env": {
        "AKATSUKI_VAULT": "/path/to/your/knowledge-base"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "akatsuki": {
      "command": "akatsuki",
      "args": ["mcp"]
    }
  }
}

Antigravity (~/.gemini/antigravity-cli/mcp/) / OpenCode / pi

{
  "mcpServers": {
    "akatsuki": {
      "command": "akatsuki",
      "args": ["mcp"]
    }
  }
}

🛠️ Complete MCP Tools Reference (20 Tools)

⚡ Vault Discovery Ladder

Akatsuki locates the target knowledge base automatically using a multi-tiered resolution ladder:

1. CLI Flag: --vault /path/to/vault (or -V)

2. Environment Variable: AKATSUKI_VAULT=/path/to/vault

3. Upward Directory Walk: Traverses upwards looking for .akatsuki/ or INDEX.md + AGENTS.md.

4. Well-Known Locations: Checks ~/configs/knowledge-base/akatsuki, ~/.akatsuki, ~/akatsuki.

5. Fallback: Current working directory.

🧪 Testing

Akatsuki is validated against an exhaustive regression and integration test suite:

# Run complete test suite (unit, CLI, and regression tests)
cargo test

# Run tests with output
cargo test -- --nocapture

The test harness asserts:

• Path traversal underflow containment and internal .akatsuki/ mutation isolation.

• Read-only SQLite query validation and mutating CTE / SQL injection prevention.

• Security gate blocking destructive invariant commands (rm, dd, mkfs, fork bombs).

• Invariant timeout handling and asynchronous output buffer draining (capped at 2 MB).

• Wikilink code fence stripping and heading extraction with emoji/punctuation normalization.

• Token sequence clamping (512 tokens) to protect BERT positional embeddings.

📜 License

MIT License. Copyright (c) 2026 Yusuf Akçakaya.