🌅 Akatsuki (暁)

Universal CLI and Model Context Protocol (MCP) Gateway for Living System Memory and Architectural Contracts for Autonomous AI Agents.

🏛️ 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:

• Machine-Verifiable Contracts: Inspect living system contracts, service boundaries, and cluster topology before mutating code.

• Living Invariant Testing (bash:verify): Test system health against machine-executable verification assertions embedded directly within Markdown notes.

• Fast Okapi BM25 Search: Zero-daemon, in-process SQLite full-text search with morphological expansion and excerpt ranking.

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

• Zero Runtime Dependencies: Written entirely in Python standard library (sqlite3, pathlib, argparse, fcntl, json). No heavy dependencies, no build friction.

Related MCP server: synapse

🚀 Quick Start

1. Installation

Option A: Standard Installation (Pure Standard Library, Zero Dependencies) Runs with pure in-process Okapi BM25 ranking, instant startup, zero dependencies:

# Via pip
pip install git+https://github.com/fusuyfusuy/akatsuki.git

# Or via uv tool
uv tool install git+https://github.com/fusuyfusuy/akatsuki.git

Option B: With Semantic Vector Embeddings & Hybrid RRF Search (Optional Extra) Equips Akatsuki with local offline semantic search powered by intfloat/multilingual-e5-small (384D) clamped safely to 2 CPU threads:

# Via pip
pip install "akatsuki[embeddings] @ git+https://github.com/fusuyfusuy/akatsuki.git"

# Or via uv tool with lightweight CPU PyTorch wheel:
uv tool install --editable /path/to/akatsuki --with sentence-transformers --with torch --extra-index-url https://download.pytorch.org/whl/cpu --force

2. Bootstrap a Living Memory Vault

# Initialize a fresh living memory vault in the current directory or specified path
akatsuki init ./knowledge-base

cd ./knowledge-base

This creates the standard Akatsuki vault structure:

knowledge-base/
├── .akatsuki/          # Local SQLite BM25 + vector search index and locks (gitignored)
├── .gitignore          # Pre-configured multi-machine ignores
├── 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

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

# Pure semantic vector search
akatsuki search "hardware specifications of primary host" --mode vector

# Read a note or specific section with token budget packing
akatsuki read "Cluster-Topology" --section "Private Network Routing"

# Calculate blast radius for a service before making changes
akatsuki blast auth-service

# Run living invariant checks across system documentation
akatsuki test

# Record a telegraphic caveman ledger entry
akatsuki log -p "web" -s "migrate edge certs -> let encrypt automated; exit 0"

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

🤖 MCP Server Setup (for AI Agents)

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

akatsuki mcp

Claude Desktop Configuration (claude_desktop_config.json)

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

Cursor Configuration (.cursor/mcp.json)

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

Antigravity / OpenCode / pi Configuration

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

🛠️ MCP Tools Reference

⚡ 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 from the current directory 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 comes with a comprehensive standard test suite with zero test dependencies:

# Run tests using Python standard library unittest
python3 -m unittest discover tests -v

📜 License

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