Confucius Code Agent
Scalable Agent Scaffolding for Real-World Codebases — A framework demonstrating that success in code agents depends not on the LLM alone, but on the scaffolding around it.
Overview — What the Paper Presents
CCA (Confucius Code Agent)
A new high-performance code agent for large-scale software engineering.
Confucius SDK
A modular platform for building AI agents with extensibility, transparency, and interpretability.
What's Revolutionary
Intelligent Memory Hierarchy
Uses a planner agent ("Architect") to summarize conversations, keeping only the essential. Enables long reasoning without exceeding context limits.
Persistent Note-Taking
Records not just successes, but also errors and failed strategies. The agent "learns from its mistakes" and doesn't start from scratch.
Modular Extensions System
Modular extensions for code editing, search, command execution. Easy to add, replace, or improve functionality.
Automatic Meta-Agent
An agent that builds and improves other agents: tests configurations, evaluates performance, and adjusts prompts automatically.
Key Advantages
| Feature | Advantage |
|---|---|
| Hierarchical Memory | Handles large codebases and long sessions without losing context |
| Persistent Note-Taking | Improves with accumulated experience between sessions |
| Modular Extensions | Easy adaptation and integration with existing tools |
| Meta-Agent | Automates agent creation and refinement |
| Transparency | More interpretable and auditable than proprietary systems |
"An AI agent for software engineering that is scalable, modular, with long-term memory and automatic improvement mechanisms — enabling better work with large real-world codebases."
The Problem: Why Current Agents Fail at Scale
Existing coding agents struggle with enterprise-level software engineering due to two core challenges:
Long-Context Reasoning
Agents must efficiently localize relevant code within massive repositories and perform multi-hop reasoning across dispersed modules, long tool traces, and deep execution histories.
Long-Term Memory
Agents should accumulate persistent knowledge across tasks and sessions—capturing reusable patterns, failure modes, and invariants—rather than repeatedly rediscovering information.
Key Insight: Scalability requires more than longer context windows or larger models—it requires a principled approach to how agents structure, maintain, and interact with external information.
Design Philosophy: AX, UX, and DX
Most agent frameworks optimize for a single audience. Confucius SDK adopts a three-axis design philosophy that treats Agent Experience, User Experience, and Developer Experience as first-class and interdependent concerns.
Agent Experience (AX)
The agent's internal cognitive workspace: which information it receives and how it's structured.
- Distilled working memory
- Hierarchical memories
- Adaptive summaries
User Experience (UX)
How humans observe and interact with the agent. Prioritizes transparency and interpretability.
- Readable logs
- Execution traces
- Artifact previews
Developer Experience (DX)
Building, inspecting, and improving agents with modular interfaces and observability.
- Reproducibility
- Ablations & debugging
- Rapid iteration
Example: AX vs UX Separation
Creating file at config.py
File created successfully at config.py
Here is the diff:
+ PORT=8080
+ DEBUG=true
+ MAX_CONNECTIONS=100Human: [previous user message]
AI: <file_edit type="create"
file_path="config.py">...
Human: <result>File created
successfully</result>Users see rich streaming updates; the agent sees only compressed summaries.
SDK Architecture
The Confucius SDK provides a modular foundation. The Meta-Agent automates the build-test-improve loop, while the Code Agent is instantiated with specific extensions for software engineering tasks.
Confucius SDK
Core components: Orchestrator, Memory, Extensions
Meta-Agent
Synthesizes configs & prompts, selects SDK components automatically
Code Agent
Instantiated with bash tools, file edit, note-taking for SE tasks
The Orchestrator
A minimal yet extensible execution loop that invokes the LLM, interprets outputs, and coordinates tool use. Supports multi-step reasoning, long-term memory, and extension-based integrations.
Long-term Memory
Read/Write across sessions
Orchestrator
System Prompt → LLM → Output
Extensions
Plug-ins, APIs, Tools
Environment
File System, DB, Console
Four Core Mechanisms (F1-F4)
Context Management
Hierarchical working memory with adaptive compression. An "Architect" agent analyzes conversation history and constructs structured summaries preserving key categories.
+-- instance_qutebrowser__qutebrowser-c09e...
+-- hierarchical_memory_3a7488c6-bf8c...
+-- qutebrowser_process_cleanup
|-- analysis.md
|-- implementation_summary.md
+-- todo.md
Note-Taking Agent
Transforms interaction traces into structured persistent knowledge. Markdown notes stored in a file-system-like tree with special emphasis on hindsight notes for failures.
Note Structure
project/architecture.md
research/findings.md
solutions/bug_fix.md
Hindsight Learning
Records failures indexed by error messages, stack traces, and affected components for future retrieval.
Extensions System
Modular components that attach to the orchestrator via typed callbacks. Cover perception, reasoning, and action—separating orchestration logic from tool implementation.
Perception
Parse outputs → actions
Reasoning
Rewrite/annotate prompts
Action
Execute tools, persist
Meta-Agent
Automates agent design through an explicit Build → Test → Improve loop. Turns agent development into an agentic, evaluation-driven automatic process.
The production Confucius Code Agent itself is the outcome of Meta-agent's loop.
Benchmark Results: SWE-Bench-Pro
CCA consistently surpasses baselines across different backbone models. Scaffolding matters more than raw model capability—even a weaker model with strong scaffolding outperforms a stronger model with weaker scaffolding.
| Model | Scaffold | Resolve@1 |
|---|---|---|
| Claude 4.5 Opus | CCA | 54.3% |
| Claude 4.5 Sonnet | CCA | 52.7% |
| Claude 4.5 Opus | Anthropic | 52.0% |
| Claude 4.5 Sonnet | Live-SWE-Agent | 45.8% |
| Claude 4 Sonnet | CCA | 45.5% |
Key Insight: Claude 4.5 Sonnet + CCA (52.7%) outperforms Claude 4.5 Opus + Anthropic's scaffold (52.0%)! A weaker model with better scaffolding beats a stronger model.
Improvements arise purely from stronger agentic scaffolding—enhanced orchestration, context management, and tool-use extensions—not from differences in backbone models.
Developer Tools
The SDK provides a full suite of developer tools to support the build-test-improve loop:
Trace UI
Fine-grained visualization of call stacks, tool interactions, memory flows
Playground
Interactive environment for prompt refinement and parameter tuning
Eval UI
Built-in regression tests, A/B comparisons, benchmark evaluations
Agent Management
Unified interface for developing, deploying, monitoring at scale
Future Work: RL-Based Improvements
The paper outlines promising directions for enhancing code agents through reinforcement learning:
Trajectory-Friendly AX
The Agent Experience framework structures traces suitable for RL training via Markov Decision Process modeling.
Rich Reward Signals
Meta-agent produces fine-grained feedback from tool extensions and environment interactions for diverse reward functions.
Curriculum Design
Extension system enables progressive toolsets and environments for generalizable agentic capabilities.
Key Takeaways
Scaffolding > Raw Model Power
Orchestration, memory, and tooling around the LLM are as critical as the model itself.
Separate AX, UX, and DX
Avoid passing human traces directly to agents. Compress for AX, expand for UX.
Hierarchical Memory + Compression
Structure info into goal/plan/key_facts/recent with adaptive summarization.
Persistent Notes Enable Learning
Markdown notes with hindsight carry knowledge and failure cases between sessions.
Modular Extensions
Separate tool implementation from orchestration for testability and reuse.
Meta-Agents Automate Improvement
Build → Test → Improve loops find optimal configurations automatically.
Ready to Build Your Own?
Explore our hands-on implementation with working Python code, WebUI demo, and step-by-step explanations.
Go to Hands-on Lab