C-Agent

Controller-Agent is a controller-governed local AI harness for research-style agents.

It combines identity, memory, capabilities, and a bounded micro-run workflow so an agent can:

• form a candidate answer
• validate that answer with allowed evidence and tools
• execute grounded controller actions
• work through the full active task queue in one invocation
• preserve memory and task history
• fail honestly when no validation path exists

Current release stage: MVP-Alpha

What This Project Is

C-Agent is not a general autonomous AGI shell. It is a structured local runtime for agents that need:

• explicit identity files
• local memory logs
• controller-governed tool access
• bounded micro-runs for reasoning and validation
• honest unresolved behavior when evidence is weak

It is a good fit for:

• decomposed research tasks
• structured strategy work
• local-file-grounded tasks
• controller-driven experimentation with smaller local models

It is not yet strong at:

• giant one-shot briefs without decomposition
• broad web research out of the box
• permissive freeform tool execution
• perfect deliverable-quality verification

What Ships In This OSS Runtime

This extracted repo contains the runnable agent runtime, including:

• agent.py
• config.json
• controller/
• identity/
• memory/
• scripts/

It does not ship the full internal source-repo test and planning surface.

Quick Start

Requirements

• python3
• npm
• Ollama if you are using a local Ollama endpoint
• a pulled local model matching config.json (default: qwen2.5:3b)

1. Review config

Check:

• config.json
• controller/mcp-config.json

Optional examples are included here too:

• config.example.json
• controller/mcp-config.example.json

2. Prepare the runtime

npm run build:prod

This will:

1. run production preflight
2. verify Python entrypoints compile
3. reset mutable runtime files to factory defaults

3. Add tasks

Write one or more task lines to identity/current-tasks.md:

- your task here
- another task here

4. Inspect startup payload (optional)

npm run inspect:startup

5. Run the agent

python3 agent.py

Runtime Flow

At a high level, C-Agent does this:

1. load identity, memory, capabilities, startup files, and config
2. read active tasks from identity/current-tasks.md
3. for each active task, run bounded workflow micro-runs:
   • question normalization
   • candidate answer
   • answer synthesis
   • answer verification
   • action selection when more evidence is needed
   • JSON repair when model output is malformed
4. execute only approved controller actions
5. reconcile each finished task back into memory
6. refresh task state from memory
7. clean up the local model runtime when the batch ends

For a fuller walkthrough, see ARCHITECTURE.md.

Commands

npm run compile
npm run build:dev
npm run build:prod
npm run reset
npm run inspect:startup

Notes

• build:dev in this OSS runtime package is a lightweight validation pass.
• The full internal source repo contains a larger test surface than this extracted runtime package.

Configuration

Model config

The default runtime expects Ollama:

• provider: ollama
• endpoint: http://127.0.0.1:11434/api/generate
• model: qwen2.5:3b

If you use a remote/internal Ollama host, update model.endpoint in config.json before running npm run build:prod.

MCP config

The default shipped MCP config includes two public doc/research surfaces:

• Cloudflare docs MCP
• AWS Knowledge MCP

These are optional. You can disable, replace, or extend them in controller/mcp-config.json.

State Files

These files are mutable runtime state:

• controller/runtime.jsonl
• memory/memory.jsonl
• memory/extended_memory.jsonl
• identity/current-tasks.md

Use:

npm run reset

when you want a clean local runtime state.

Known Limits

• Broad strategy briefs still benefit from decomposition into smaller tasks.
• The verifier can still accept shallow answers too easily in some cases.
• MCP support is still partial; discovery is better than execution today.
• General web research is not built in by default.
• The runtime is intentionally conservative: unresolved is preferred over bluffing.

Contributing

See:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md

License

This project is released under the MIT License. See LICENSE.