kikobeep/Pikachu-Agent

阅读中文版

A local agent runtime for completing, recovering, and learning from software tasks.

Pikachu turns an LLM into a bounded coding agent. It can inspect a workspace, edit files, run verification commands, maintain task state, and continue interrupted work with the context that matters.

Understand → Act → Verify → Recover → Learn

These recordings show Pikachu running in the local TUI.

• CLI welcome screen in iTerm2

• PLAN MODE and sequential plan execution

Download the PLAN MODE demo video

• Memory

Create a memory	Search a memory

• Context compaction and summary

Download the context compaction demo video

• Why Pikachu
• What Pikachu provides
• Architecture
• Quick Start
• Polyglot evaluation
• Experimental results
• MemoryBenchEval
• Project layout
• Troubleshooting

Most coding-agent demos show the visible loop: a prompt goes in and a code change comes out. Pikachu focuses on the engineering system around that loop—how an agent acts inside a real workspace, keeps the right context, verifies its work, and continues after interruption.

Pikachu is intentionally a local, inspectable runtime rather than a full product platform. Its scope is small enough that the execution loop, context pipeline, persistence layer, and learning mechanisms can be read and adapted end to end.

The goal is not to maximize the number of platform features. It is to provide a complete enough agent runtime that its behavior can be inspected, measured, and extended without losing sight of the underlying execution model.

• Model-driven agent loop with file and shell tools;
• workspace and permission boundaries;
• limits for steps, tool rounds, model calls, and token usage;
• checkpoints and resumable runs.

Pikachu assembles six kinds of context before each model request:

• History — current conversation and tool results;
• Memory — persistent user preferences, facts, and constraints;
• Skill — on-demand operational knowledge;
• Task — current goal, state, and recovery checkpoint;
• Summary — compressed older conversation history;
• Experience — reusable strategies from the ACE Playbook.

Long contexts are reduced in two stages. ToolReducer performs type-aware compaction for JSON, test output, diffs, search results, and similar tool content. If the request is still too large, ConversationReducer summarizes older conversation blocks while protecting recent context.

• Continue — resume interrupted work from Task context, Checkpoints, and Conversation State;
• Skill Improve — analyze successful and failed runs, distill reusable procedures, and create Skill candidates;
• ACE Learn — reflect on real task outcomes and update a sectioned Playbook through Reflector and Curator.

User request
     │
     ▼
Agent Loop ──────── Tools ──────── Workspace / Sandbox
     │
     ├── Context Runtime
     │     ├── History and Summary
     │     ├── Memory
     │     ├── Skill
     │     └── Task / Checkpoint
     │
     └── Learning
           ├── Skill Improve
           │     ├── Success Analyst
           │     ├── Failure Analyst
           │     └── Skill Candidate
           └── ACE
                 ├── Reflector
                 ├── Curator
                 └── Playbook

In multi_teacher mode, Skill Improve analyzes successful and failed evidence separately:

Completed runs
     ↓
Success Analyst  ── reusable behaviors and verification patterns
Failure Analyst  ── symptoms, causes, and prevention actions
     ↓
Merge, deduplicate, and resolve conflicts
     ↓
Skill candidate → review or auto-accept → installed Skill

Failure traces are converted into constraints, preventive checks, repair actions, or a small Common failures section rather than copied into recommended procedures.

ACE provides reusable task experience through a sectioned Playbook:

Agent reads the Playbook
     ↓
Agent reports the bullet IDs it used
     ↓
Reflector evaluates those bullets
     ↓
Curator emits ADD / UPDATE / MERGE / DROP
     ↓
Playbook analysis and deduplication
     ↓
Playbook is saved

Playbooks are stored at .database/ace/<language>_playbook.txt.

• Python 3.13 or newer;
• pipx;
• an API key for a supported model provider;
• Node.js for JavaScript evaluation;
• a C++ compiler and CMake for C++ evaluation.

git clone https://github.com/kikobeep/Pikachu.git
cd Pikachu

pipx install ./backend

If pipx is not installed, install it first. On macOS with Homebrew:

brew install pipx
pipx ensurepath

On other platforms, follow the pipx installation guide.

To install the local checkout in editable mode while developing Pikachu:

pipx install --editable ./backend

Create backend/.config:

MODEL_DEFAULT_PROVIDER=deepseek
DEEPSEEK_API_KEY=your-api-key
DEEPSEEK_MODEL=deepseek-v4-flash
DEEPSEEK_BASE_URL=https://api.deepseek.com

Do not commit API keys. The backend loads this file at startup; environment variables can also be used.

pikachu

Pikachu starts the TUI directly. If no model provider has been configured yet, it opens the setup flow automatically. You do not need to enter backend, activate a virtual environment, or run python -m app --setup manually.

Run one exercise first:

PYTHONPATH=backend \
backend/.venv/bin/python \
eval/run_polyglot_eval.py \
  --language python \
  --exercise book-store \
  --feedback \
  --ace \
  --report python_book_store_ace.json

Run all exercises for one language:

PYTHONPATH=backend \
backend/.venv/bin/python \
eval/run_polyglot_eval.py \
  --language python \
  --feedback \
  --ace \
  --report python_ace.json

Run the same benchmark twice with the same model, order, budget, and feedback settings:

# Round 1: build the Playbook
PYTHONPATH=backend \
backend/.venv/bin/python eval/run_polyglot_eval.py \
  --language python --feedback --ace \
  --report python_ace_round1.json

# Round 2: reuse the Playbook
PYTHONPATH=backend \
backend/.venv/bin/python eval/run_polyglot_eval.py \
  --language python --feedback --ace \
  --report python_ace_round2.json

This measures online adaptation, not unbiased generalization. Use unseen exercises for independent generalization.

The two tables represent different learning mechanisms and should not be interpreted as one combined ablation.

The edit statistics use the edit_attempts field from the corresponding before and ACE JSON reports.

MemoryBenchEval evaluates whether an agent can retrieve relevant memories and use them to improve its answer. We use MemoryBenchEval_star dataset.

The primary metrics are:

• Extract Match — whether the answer extracts the required information;
• F1 — token-level answer overlap;
• substring exact match — whether the reference answer appears in the prediction;
• ROUGE-L F1 — sequence-level overlap based on the longest common subsequence.

For the four metrics above, the reported results are grouped by agent family:

Compared with Pikachu without ACE, adding ACE improves all four reported metrics:

The original experiment notes also contain additional score values for Deepseek and BM25 beyond the four columns shown above. The table keeps the values that map directly to the named metrics; the remaining reported values are preserved below until the original column grouping is confirmed:

The benchmark metric definitions follow MemoryAgentBench's evaluation mapping; in particular, Accurate Retrieval uses substring_exact_match as its accuracy field.

Pikachu-main/
├── backend/
│   ├── app/
│   │   ├── agent/              # Agent loop, runtime, budgets, context injection
│   │   ├── ace/                # ACE coordinator, Reflector, Curator, Playbook
│   │   ├── checkpoint/         # Checkpoint persistence and recovery
│   │   ├── context/            # Token budgets, tool compaction, summaries
│   │   ├── conversation/       # Conversation models and persistence
│   │   ├── evidence/           # Durable tool evidence and evidence tools
│   │   ├── memory/             # Core/Regular memory and retrieval
│   │   ├── model/              # Provider configuration and adapters
│   │   ├── run/                # Run lifecycle and outcomes
│   │   ├── sandbox/            # Workspace and command isolation
│   │   ├── skills/             # Skill storage and activation
│   │   ├── skills_improve/     # Skill analysis, distillation, candidates
│   │   ├── task/               # Task context and task tools
│   │   ├── tools/              # Tool registry, permissions, and execution
│   │   └── trace/              # Run traces and usage records
│   ├── requirements.txt
│   ├── .config                 # Local model/provider configuration
│   ├── .database/               # Runtime and evaluation databases
│   ├── .memory/                 # Local memory store and search index
│   └── .skills/                 # Skill-improvement candidates and state
├── eval/
│   ├── run_polyglot_eval.py    # Polyglot benchmark runner
│   ├── run_skill_improve_*.py  # Skill-improvement evaluation helpers
│   └── polyglot-benchmark-main/ # Benchmark exercises
├── .database/ace/              # Language-specific ACE Playbooks
├── workspace/                   # Runtime/evaluation workspace
└── README.md

Run from the repository root and set PYTHONPATH=backend:

PYTHONPATH=backend backend/.venv/bin/python eval/run_polyglot_eval.py --language python

Install pytest into the interpreter used by the evaluation command:

uv pip install --python backend/.venv/bin/python pytest

backend/.venv/bin/python -c \
  "import sys; print(sys.executable); print(sys.version)"

ACE can use a locally cached sentence-transformers/all-MiniLM-L6-v2 model for bullet deduplication:

uv pip install \
  --python backend/.venv/bin/python \
  sentence-transformers

The implementation uses local_files_only=True; if the model or dependency is unavailable, ACE falls back to lightweight lexical similarity.