aikito

简体中文 · Documentation

Aikito is a Git-managed workspace for governing AI-agent context and durable memory.

   Aikito  =  governing agent resources  ×  curating durable memory

Plain files define the source of truth, explicit scopes define who sees what, and Git keeps the history.

Aikito governs the workspace, agents maintain the memory, and you oversee it all.

One workspace keeps your AI workflow consistent across agents and machines.

Why Aikito

AI agent resources fragment in three directions:

• Across tools: each agent requires a different configuration format
• Across projects: reusable knowledge, skills, and instructions are copied or maintained across multiple repositories
• Across time: valuable decisions and hard-won lessons disappear into old sessions

Aikito keeps all of it in one personal Git workspace and exposes selected resources to each agent and project:

~/aikito
├── skills/                         shared reusable skills
├── memory/                         global durable memory
├── global/                         global instructions
├── mcps/                           shared MCP definitions
├── subagents/                      shared reusable subagents
└── projects/
    └── <project-name>/
        ├── agent.toml              selected shared resources
        ├── AGENTS.md               project instructions
        └── memory/                 project durable memory
            ├── index.md
            └── notes/

No database, daemon, vector store, or hosted service required.

What Aikito Manages

The default registry includes Codex, Claude Code, Antigravity CLI (agy), OpenCode, GitHub Copilot CLI, DeepSeek Harness (dsh), Grok Build, and Pi. See the architecture for the complete mental model and capability boundaries. Pi participates in instructions, skills, and runners. It does not participate in MCP or subagent synchronization, which pi leaves to optional extensions.

Share or isolate

• link keeps a resource shared and immediately up to date
• copy gives a project an isolated snapshot it can evolve independently
• project memory always uses link mode with its canonical scope, preserving one history

Durable Memory

The bundled durable-memory skill is the curation half of the equation. It guides coding agents to retrieve relevant notes before acting, distill durable conclusions from what they learn, update notes that went stale, and choose the right global or project scope.

New workspaces enable this workflow by default: initialization creates the Memory structure, installs and selects the bundled aikito and durable-memory skills, and adds the minimal global instruction that requires Agents to evaluate Memory relevance. Nothing is connected to an Agent until you explicitly run aikito sync global. See Default behavior and opt-out for the complete lifecycle.

The notes are ordinary Markdown, so Git gives you history, review, rollback, and portability — and the memory an agent wrote in Claude Code yesterday is the same memory Codex reads tomorrow.

Automation is not the same as governance. Read Memory Needs a Maintainer to see why Aikito keeps people responsible for the meaning, scope, and lifecycle of memory and skills—even when agents perform most maintenance work.

aikito show memory lists what has accumulated, grouped by scope. A typical example looks like this:

┌────────┬───────────────────────┬─────────────────────────────────────┬───────┬──────┐
│ Scope  │ Note File             │ Title                               │ Index │ Link │
├────────┼───────────────────────┼─────────────────────────────────────┼───────┼──────┤
│ Global │ commit-message-style  │ Conventional commits, English only  │ ✓     │ –    │
│ Global │ review-tone           │ Ask before large refactors          │ ✓     │ –    │
├────────┼───────────────────────┼─────────────────────────────────────┼───────┼──────┤
│ aikito │ architecture-decisions│ Stable project design constraints   │ ✓     │ ✓    │
│ aikito │ release-checklist     │ Tag only after tests pass           │ ✓     │ ✓    │
├────────┼───────────────────────┼─────────────────────────────────────┼───────┼──────┤
│ blog   │ draft-workflow        │ Drafts live in content/ until dated │ ✓     │ ✓    │
└────────┴───────────────────────┴─────────────────────────────────────┴───────┴──────┘

Global notes are available everywhere; each project's notes are linked only into that project. In this example, an agent working in aikito sees only the global notes plus aikito's own notes, and nothing from blog.

Use aikito maintain memory for confirmation-gated, full-scope maintenance; see Proactive Scope Maintenance.

Web Console

Browse your workspace, resources, scopes, and governance state in a local, read-only interface:

aikito web

The console binds to 127.0.0.1 and provides a visual view of the canonical workspace without changing its resources.

Boundaries

Aikito manages durable files, explicit scopes, and controlled synchronization. To stay lightweight and portable, it deliberately does not:

• capture every agent action or conversation automatically
• run a vector store, embedding pipeline, or memory service
• inject context into every prompt through a background daemon
• orchestrate supervisor and worker agents
• replace your coding agent's native runtime

Aikito governs the workspace, your agent reasons and maintains the memory, and you oversee it all.

Requirements

• macOS or Linux; Windows users should use WSL2.
• Python 3.12, 3.13, or 3.14.
• Git.

Native Windows is not supported: Aikito relies on symbolic links and POSIX file permissions for synchronization and credential safety.

Quick Start

Option 1: Let Your Coding Agent Set It Up (Recommended)

Install and configure Aikito from https://github.com/lsaint/aikito. Read the README, skills/aikito/SKILL.md, and any linked documentation relevant to the setup, then follow their safety requirements to initialize the workspace, synchronize its global resources, and verify the result with aikito status. Before importing or changing any existing Agent configuration, show me the planned changes and conflicts and wait for my approval. When setup is complete, summarize what is ready and guide me through the next step, including whether to register my first code project. Do not register a project without my confirmation.

If you use this option, your coding agent performs the installation and setup; you do not need to also follow the manual commands below.

For project registration, resource management, diagnostics, and Memory maintenance prompts, see Agent-first workflows.

Option 2: Set It Up Manually

brew install lsaint/tap/aikito

aikito init workspace ~/aikito
aikito sync global
aikito status

Installing via Homebrew automatically sets up Tab completion for Zsh, Bash, and Fish — no extra configuration needed.

For manual installs, add one line to ~/.zshrc:

eval "$(aikito completion zsh)"

The workspace is the single Git-managed home for all Aikito resources. You normally initialize one workspace per user or machine.

Register each code project that needs project-specific instructions, skills, or memory. From the project directory:

cd ~/code/example
aikito init project

This creates the project's canonical resources under <workspace>/projects/example/ and connects them to ./.agents/. One workspace can manage many projects; a project registration represents one code directory and its project-specific Agent resources, not the project source code itself.

When initialized at a custom path, Aikito remembers it for future commands. Use aikito path workspace to print the active path. AIKITO_DIR provides a temporary override, which is useful for CI and isolated automation.

aikito status reports resource state across supported agents:

┌───────────────────────┬──────────────┬────────┬────────────┬───────────┐
│ Agent                 │ Instruction