Aki

Persistent project memory and operational context for AI coding agents.

Built for the Qwen Cloud Global AI Hackathon Series, Aki turns a repo into a durable workspace an agent can return to: project memory, resumable sessions, operational posture, MCP bootstrap, and SDD-aware context in one local-first tool.

Why Aki

AI coding agents are powerful, but they forget too much between sessions.

Aki fixes that by giving agents a persistent, project-scoped memory layer and a repo-aware operating surface. Instead of starting every session from scratch, an agent can recover prior decisions, resume a session checkpoint, inspect project health, and work with the same conventions the repo already established.

This repository is intentionally positioned as an open-source hackathon product, not a hosted SaaS:

• local-first by default;

• MCP-native for real coding-agent workflows;

• Qwen-powered when cloud extraction/explanations help;

• useful without Qwen credentials for core memory and audit flows.

Related MCP server: Claude Habitat

What makes it submission-ready

Product strengths

Demo value in one sentence

Aki helps an agent behave less like a stateless chatbot and more like a repo-aware engineering teammate.

Quickstart

Requirements

• Python 3.11+

• uv

• Optional: QWEN_API_KEY or DASHSCOPE_API_KEY for Qwen-powered extraction/explanations

Fastest path: one command

No clone, no manual steps. This clones the repo into ./aki, installs uv if needed, syncs dependencies, installs the aki CLI as a global tool, and runs aki setup (config bootstrap + health check) — all in one shot:

curl -fsSL https://raw.githubusercontent.com/Akicoders/aki/main/install.sh | sh

It's safe to re-run at any time (idempotent), and works the same way if you run it from inside an existing clone (sh install.sh) instead of piping it.

If you want manual control, already have a partial setup, or want to pass explicit flags (e.g. --qwen-api-key), follow the numbered steps below instead.

1) Install and sync

git clone https://github.com/Akicoders/aki.git
cd aki
uv sync --all-extras

Or use the installer, which also installs the aki uv tool and runs aki setup (config bootstrap + health check) automatically at the end — no follow-up command needed:

sh install.sh

2) Verify the environment

Only needed if you used the manual uv sync --all-extras path above; sh install.sh already runs this for you as its last step.

uv run aki doctor

3) Open the product surface

Run Aki inside a git project with no subcommand:

uv run aki

This opens the operational cockpit, which summarizes:

• project health;

• pending action items;

• memory posture;

• SDD status.

4) Generate an audit report

uv run aki audit aki

Audit reports are written to docs/audits/ and cover tests, SDD, git hygiene, env/config, MCP readiness, and memory posture.

5) Connect Aki to an MCP host

Generate config:

uv run aki mcp-config opencode
uv run aki mcp-config claude-code

Or apply it automatically:

uv run aki mcp-setup opencode
uv run aki mcp-setup claude-code

6) Start the MCP server

uv run aki mcp

Core capabilities

Persistent memory for coding workflows

Aki stores:

• events for conversational history and activity;

• facts for durable project knowledge;

• procedures for repeatable workflows;

• decisions that should influence future agent behavior.

Core memory tooling is available through MCP:

• memory_context

• memory_search

• memory_save

• memory_extract

• memory_explain

Without Qwen credentials, memory_save, memory_search, and memory_context still work.

Resumable sessions

Interactive mode supports explicit sessions, auto-resume through session:last, and checkpoint rehydration per session:

uv run aki interactive
uv run aki interactive --new-session
uv run aki interactive --profile reviewer

Inside interactive mode, /sessions lists prior sessions for the current project.

Specialized agent profiles

Aki includes a profile system for specialized agents with scoped tools and memory policies.

Inspect configured profiles:

uv run aki agents

See docs/agent-profiles.md for the configuration model.

Operational cockpit and project registry

Browse known projects and jump into their cockpit views:

uv run aki projects browse
uv run aki cockpit --interactive

This makes Aki more than a memory store: it becomes a lightweight control plane for agent-ready repositories.

SDD-aware development

Aki detects Spec-Driven Development artifacts in docs/sdd/, .sdd/, or openspec/ and can bootstrap a new SDD workspace:

uv run aki sdd-init

This is especially useful for hackathon demos because it shows memory, planning, and delivery working together in one workflow.

Configuration

For manual setup:

cp .env.example .env

Relevant Qwen / DashScope settings:

QWEN_API_KEY=your_qwen_api_key_here
# or
# DASHSCOPE_API_KEY=your_dashscope_api_key_here
QWEN_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
QWEN_MODEL=qwen3.7-max
QWEN_EXTRACTION_MODEL=qwen3.7-plus
QWEN_CONSOLIDATION_MODEL=qwen3.7-max
QWEN_EMBEDDING_MODEL=text-embedding-v3

Relevant local storage defaults:

MEMORY_DB_PATH=data/agentos.db
MEMORY_CHROMA_PATH=data/chroma_db
MEMORY_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
MEMORY_MAX_CONTEXT_TOKENS=8000

Demo framing

If you are evaluating Aki as a hackathon product, the strongest sequence is:

1. open the cockpit with uv run aki;

2. run uv run aki audit aki to show structured repo assessment;

3. show uv run aki agents to demonstrate specialized agent profiles;

4. generate host bootstrap with uv run aki mcp-config opencode or aki mcp-setup --dry-run;

5. demonstrate interactive/session continuity or MCP memory retrieval.

Use these docs for the full evaluator path:

• docs/demo.md — evaluator walkthrough

• docs/demo-script.md — short live demo script

• docs/devpost-description.md — submission copy

Architecture at a glance

flowchart TD
    %% Define Styles
    classDef external fill:#f9f9f9,stroke:#333,stroke-width:2px,color:#333
    classDef core fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b
    classDef memory fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#f57f17
    classDef feature fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef llm fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px,color:#4a148c
    
    %% External Interfaces
    subgraph Interfaces ["External Interfaces"]
        IDE["AI Coding Host<br>(OpenCode, Claude Code)"]:::external
        CLI["Aki CLI<br>(uv run aki)"]:::external
    end
    
    %% Entrypoints
    subgraph Entrypoints ["Aki Entrypoints"]
        MCP["MCP Server<br>(stdio)"]:::core
        Cockpit["Cockpit Surface"]:::core
    end
    
    %% Core Modules
    subgraph Core ["Aki Core Modules"]
        MemH["Memory Handlers"]:::feature
        QwenC["Qwen Client"]:::feature
        Audit["Audit System"]:::feature
        SDD["SDD Detection<br>(Spec-Driven Dev)"]:::feature
        Agent["Agent Profiles"]:::feature
        Skills["Skills & Tools"]:::feature
    end
    
    %% Data & External Services
    subgraph Storage ["Storage & External Services"]
        SQL["SQLite<br>(Structured Data)"]:::memory
        Chroma["ChromaDB<br>(Vector Embeddings)"]:::memory
        QwenAPI["Qwen API<br>(DashScope)"]:::llm
    end
    
    %% Relationships
    IDE -- "MCP Protocol (stdio)" --> MCP
    CLI -- "Terminal" --> Cockpit
    CLI -- "Commands" --> Audit
    CLI -- "Interactive Sessions" --> Agent
    
    MCP --> MemH
    MCP --> SDD
    MCP --> Skills
    
    Cockpit --> Audit
    Cockpit --> MemH
    Cockpit --> SDD
    
    MemH --> SQL
    MemH --> Chroma
    
    QwenC --> QwenAPI
    MemH -. "Extraction & Embeddings" .-> QwenC
    Agent -. "LLM Inference" .-> QwenC

Public CLI entry point:

aki

Compatibility alias retained during transition:

agentos

Related docs

• docs/integration.md — host integration details

• docs/agent-profiles.md — specialized profile configuration

• docs/troubleshooting.md — common setup issues

• docs/sdd/ — proposal, spec, design, and task artifacts

• CONTRIBUTING.md — contributor workflow

Development quality

The repository includes:

• GitHub Actions CI for linting and tests;

• a dedicated pytest suite under tests/;

• a documented development flow in CONTRIBUTING.md.

Typical local checks:

uv run ruff check .
uv run pytest tests/ -q
uv run aki mcp-config opencode

Scope and non-goals

Aki is a strong open-source hackathon MVP, but it is not presented here as a hosted production platform.

Out of scope in this repository today:

• REST API or web dashboard

• multi-user / team tenancy

• WhatsApp, Telegram, or voice ingestion

• HTTP /health endpoints as a primary interface

Container files such as Dockerfile and docker-compose.prod.yml are deployment helpers, but the main product interface remains local stdio MCP.

License

MIT. See LICENSE.