A composable autonomous software engineering platform where coding agents act, remember, coordinate, and measure improvement across sessions.
| Layer | Project | Lang | What it does |
|---|---|---|---|
| 4 | forge-agent | Python | Continual-learning coding agent — executes tasks via TDD, learns from outcomes, improves across runs. |
| 4 | ferrum-agent | Python | Multi-agent orchestration runtime — planning, execution, review, memory, and human approval in one control plane. |
| 4 | cl-agent | Python | Reusable CL substrate — captures episodes, replays experience, and distills reusable skills without fine-tuning. |
| 4 | java-code-review-agent | Python | LangGraph ReAct review agent — deterministic static analysis (security, smells, bugs) over Java repos, LLM-enriched severity-ranked findings, optional GitHub PR comments. |
| 3 | ferrum-mcp | Rust | Coding-first MCP server — typed tool surface for agents, with optional crypto, DeFi, and memory tools. |
| 3 | ap2-rust | Rust | Agent-payments trust layer — AP2 mandates, SD-JWT chains, constraint verification, A2A helpers, CLI demos. |
| 3 | taste-memory | Python | Preference and persona memory — user profiles, versioned prompt assets, episodic interaction memory for agents. |
| 2 | ferrum-memory | Python | Memory layer — working memory, hybrid retrieval, and prioritized experience replay buffer. |
| 2 | synapse | Rust | In-memory agent task graph — Neo4j-inspired property graph for Goal / Plan / Step / Outcome recall, embeddable in-process with optional gRPC / MCP daemon. |
| 2 | ferrum-evals | Python | Evaluation harness — correctness, safety, trajectory quality, BWT/FWT continual-learning metrics. |
| 2 | PersonalKB | Python | Offline-first CLI RAG — grounded hybrid retrieval over personal technical libraries, zero API cost. |
| 1 | ferrum-gateway | Rust | Standalone service gateway — generic HTTP routing, auth, limits, streaming, metrics; optional LLM/MCP/Ferrum adapters. |
| 1 | secure-agent-runner | Rust | Standalone execution plane — policy-checked jobs, workspace snapshots, capped output/artifacts, replayable results. |
| 1 | axon | Rust | Local inference server — dynamic batching, SSE streaming, three-tier fallback, TurboQuant KV cache compression. |
| 1 | ferrum-relay | Rust | Async job relay — HTTP clients offload fetch/compute jobs, receive job IDs, poll for results. |
| 1 | tokengate | Rust | Token metering layer — usage tracking, exact-decimal billing, chargeback analytics for LLM API calls. |
| 0 | ferrum-core | Rust | Shared Rust primitives — error types, JSON logging, OpenTelemetry span export (crates.io v1.0.0). |
| 0 | forge-core | Python | Framework-agnostic domain layer — tools, schemas, guardrails, Docker sandbox, eval harness wiring. |
| 0 | nova-api-openstack | Python | OpenStack VM API proof of concept — state-machine lifecycle management, layered API design reference. |
ferrum-gatewayis not only an agent gateway; it can run standalone for normal Web2 HTTP routing, auth, rate limits, timeouts, retries, circuit breakers, streaming proxying, logs, tracing, and metrics.- In Ferrum Stack, it sits in Layer 1 in front of
axon, external LLM APIs,ferrum-mcp, and ordinary HTTP upstreams. - Ferrum-specific behavior stays adapter-based: LLM fallback, token budgets, MCP policy, and
tokengate-shaped usage events are optional, not core dependencies.
secure-agent-runner sits in Layer 1 behind agents, ferrum-mcp, and ferrum-gateway as the governed command execution plane. It records policy-checked tool/test jobs with snapshots, output/artifact caps, replay hashes, and local-now / Firecracker-planned backend boundaries.
ap2-rust sits in Layer 3 as the agent-commerce trust layer. It gives Ferrum agents verifiable user intent, checkout, payment, and receipt chains through AP2 mandates, RFC 8785 canonical JSON, JOSE signing, SD-JWT / KB-JWT / dSD-JWT delegation, constraint verification, and A2A helpers.
synapse sits in Layer 2 as the agent task-graph memory. Where ferrum-memory stores free-form episodes and vectors for hybrid retrieval, synapse stores the typed Goal / Plan / Step / Tool / Outcome graph behind each run — first-class edges, microsecond reads inside the tool-call loop, and a small Cypher subset for traversal. Default deployment is in-process (every agent links the engine); the optional synapsed daemon exposes the same engine over gRPC / HTTP / MCP when multiple agent processes need to share one memory.
java-code-review-agent sits in Layer 4 as a specialized, language-aware review surface. It runs deterministic static analysis first (regex + AST for SQLi, hardcoded secrets, insecure deserialization, code smells, and likely bugs), then a LangGraph ReAct loop lets Claude enrich findings with line-level context, fix snippets, and calibrated severity before emitting a Pydantic-validated ReviewReport and (optionally) posting GitHub PR comments. It maps onto the review step in ferrum-agent's plan → execute → review → approve loop, and its determinism-before-LLM and structured-output patterns mirror the rest of the platform.
TASKS.md / operator / external trigger
||
|| work requests, goals
||
______________________________________________________________________________
|| ||
|| LAYER 4 -- THE AGENT ||
|| ||
|| forge-agent (Python -- pure SDK, no LangGraph, no DSL) ||
|| ||
|| Wake cycle: ||
|| read TASKS.md --> build WorkspaceContext --> write failing test (TDD) ||
|| --> implement (up to 3 attempts) --> run tests --> commit if green ||
|| --> log episode { task_id, tool_calls, test_result, reward } ||
|| to ferrum-memory POST /experience ||
|| ||
|| Dream cycle: ||
|| ferrum-memory GET /replay?strategy=prioritized&k=20 ||
|| --> Anthropic API: reflect on failure patterns ||
|| --> ferrum-memory POST /memory/store (learnings as semantic mem) ||
|| --> write DREAMS.md (human-readable, read at next Wake) ||
|| --> ferrum-memory POST /session/close (consolidate working memory) ||
|| ||
|| LLM routing: ||
|| FILE_OPS --> axon (local Rust/Candle inference, 80% of all calls) ||
|| CODE_GEN --> Anthropic API (claude-sonnet-4-6, 20% of calls) ||
|| optional --> ferrum-gateway for fallback, budgets, metering, policy ||
|| command runs --> secure-agent-runner for policy, snapshots, replay ||
||____________________________________________________________________________||
|| || ||
|| MCP tool calls || episode writes || reward signal
|| || replay reads ||
|| || ||
________||_________ ____________||____________ _________||_________
|| || || || || ||
|| LAYER 3 || || LAYER 1 || || LAYER 2 ||
|| || || || || ||
|| ferrum-mcp || || ferrum-memory || || ferrum-evals ||
|| Rust MCP || || Python/FastAPI || || Python/pytest ||
|| server || || + Qdrant :6333 || || + SQLite ||
|| || || + SQLite || || ||
|| coding/* || || + Redis :6379 || || Operational: ||
|| read_file || || || || -- ToolCorrect. ||
|| write_file || || POST /experience || || -- Trajectory ||
|| apply_patch || || GET /replay || || Score ||
|| grep || || POST /memory/* || || -- Guardrail ||
|| glob || || POST /session/* || || Check ||
|| list_dir || || || || ||
|| write_test || || <-- THE replay buffer || || CL Research: ||
|| run_tests || || is the research || || -- BWT ||
|| -> runner || || || || ||
|| git_commit || || primitive -- || || -- FWT ||
|| git_status || || without it, each || || -- Plasticity ||
|| || || session starts || || Index ||
|| crypto/* (opt) || || cold, no CL || || -- Reward slope ||
|| price || || || || ||
|| position || || data stores: || || Without this, ||
|| || || Qdrant (vectors) || || "self-improving"||
|| defi/* (opt) || || SQLite (episodes) || || is a claim, ||
|| yield || || Redis (sessions) || || not a ||
|| risk_score || || || || measurement ||
||_________________|| ||________________________|| ||__________________||
||
|| shared primitives, tracing, OTel spans
||
__________||___________________________________________________________________
|| ||
|| LAYER 0 -- Infrastructure (built, published to crates.io v1.0.0) ||
|| ||
|| axon Rust local inference (HuggingFace Candle) ||
|| axon-native /v1/generate API :3000 ||
|| 80% of forge-agent LLM calls routed here ||
|| three-tier fallback: GPU --> CPU --> stub ||
|| TurboQuant KV cache compression 7x (ICLR 2026) ||
|| ||
|| ferrum-core Rust unified FaError/FaResult, fixed-schema JSON log ||
|| OTLP span export via #[instrument_fa] ||
|| no HTTP framework dep -- pure shared library ||
||____________________________________________________________________________||
______________________________________________________________________________
|| FERRUM PLATFORM ||
|| Composable autonomous software-engineering platform -- ||
|| agents that act * remember * coordinate * prove improvement ||
||____________________________________________________________________________||
TASKS.md / operator / external workflow
||
|| work requests, approvals, goals
||
______________________________________________________________________________
|| LAYER 4 -- AGENT SURFACES ||
||____________________________________________________________________________||
|| ||
|| forge-agent Python ||
|| overnight TDD coding agent with continual-learning wake/dream loop ||
|| wake: read TASKS.md --> context --> TDD loop --> commit --> log ||
|| dream: replay --> reflect --> store learnings --> DREAMS.md ||
|| routes 80% of calls to axon (local), 20% to Anthropic API ||
|| :8004 (HTTP wrapper optional in v0) ||
|| ||
|| ferrum-agent Python ||
|| multi-agent planner and orchestration control plane ||
|| LangGraph + FastAPI + Postgres + Redis + optional NATS ||
|| plan -- delegate -- execute -- review -- approve (human gate) ||
|| A2A protocol, CloudEvents, Streamlit operator UI ||
|| :8003 (Month 2 -- build after forge-agent is proven standalone) ||
|| ||
|| cl-agent Python ||
|| reusable continual-learning substrate, framework-agnostic ||
|| capture -- replay -- distillation -- evaluation ||
|| thin adapters per agent surface (Codex, LangGraph, OpenAI SDK) ||
|| extracts the learning loop from forge-agent as a portable library ||
||____________________________________________________________________________||
|| ||
|| tool calls, episodes, || persona context,
|| plans, eval events, || prompt assets,
|| approvals, rewards || user preferences
|| ||
______________________________________________________________________________
|| LAYER 3 -- TOOLING AND COORDINATION ||
||____________________________________________________________________________||
|| ||
|| ferrum-mcp Rust ||
|| coding-first MCP tool boundary -- typed action space for agents ||
|| consumers: forge-agent, ferrum-agent, native MCP clients ||
|| transport: stdio primary + SSE / HTTP :3000 ||
|| REST aliases: /tools/{tool} for compatibility ||
|| ||
|| coding domain: ||
|| read_file write_file apply_patch grep glob ||
|| list_dir write_test run_tests git_commit git_status ||
|| run_tests returns structured results; calls carry tracing fields ||
|| execution handoff: sandbox/run --> secure-agent-runner ||
|| ||
|| safety/config: ||
|| process env only; FERRUM_WORKSPACE_ROOTS guards file writes ||
|| stdio may default to cwd; HTTP requires explicit workspace roots ||
|| ||
|| optional crypto/DeFi domains: ||
|| price position yield risk_score ||
|| ||
|| optional memory domain: ||
|| search (proxy to ferrum-memory; no direct Qdrant dependency) ||
|| ||
|| taste-memory Python ||
|| human preference, versioned prompt assets, episodic interaction mem ||
|| persona injection for the ferrum-agent planner node ||
|| approves prompt material before agents see it ||
|| stores: PostgreSQL + Qdrant ||
|| :8001 (Sprint 2) ||
|| ||
|| ap2-rust Rust ||
|| agent-payments trust layer -- verifiable user intent and receipts ||
|| AP2 mandates: Intent, Cart, Payment, Receipt chains ||
|| RFC 8785 canonical JSON, JOSE signing ||
|| SD-JWT / KB-JWT / dSD-JWT selective disclosure and delegation ||
|| constraint verification, A2A helpers, CLI demos ||
|| library + CLI (no long-running service) ||
||____________________________________________________________________________||
||
|| experience writes, replay reads, knowledge lookup, scoring
||
______________________________________________________________________________
|| LAYER 2 -- MEMORY, KNOWLEDGE, AND EVALUATION ||
||____________________________________________________________________________||
|| ||
|| ferrum-memory Python ||
|| working memory + episode log + prioritized experience replay ||
|| hybrid retrieval: BM25 sparse + dense embeddings + RRF fusion ||
|| endpoints: ||
|| POST /experience -- store episode from agent run ||
|| GET /replay -- surface salient past episodes ||
|| POST /memory/* -- store / search semantic memory ||
|| POST /session/* -- open / close working memory window ||
|| stores: Qdrant (vectors) SQLite (episodes) Redis (session state) ||
|| :8000 ||
|| ||
|| synapse Rust ||
|| in-memory agent task graph -- typed Goal / Plan / Step / Outcome recall||
|| Neo4j-inspired property graph + Cypher subset + MVCC snapshot reads ||
|| slot-arena store, label + property B-tree index, lock-free snapshots ||
|| microsecond reads inside the tool-call loop ||
|| in-process by default; optional synapsed daemon over gRPC / HTTP / MCP ||
|| consumers: forge-agent, ferrum-agent, cl-agent (planner / replay) ||
|| pre-1.0 -- phases 1-3 (store / index / tx) shipped ||
|| ||
|| ferrum-evals Python ||
|| evaluation harness -- scores every CI run and overnight session ||
|| operational: ToolCorrectnessMetric TrajectoryScore GuardrailCheck ||
|| CL research: BWT (backward transfer) FWT (forward transfer) ||
|| Plasticity Index Reward curve slope ||
|| SQLite schema: task_performance table, queryable dataset ||
|| :8002 ||
|| ||
|| PersonalKB Python ||
|| offline-first CLI RAG for personal technical libraries ||
|| Ollama + BM42 sparse + Qdrant RRF -- zero API cost, local only ||
|| reference implementation of the retrieval pattern in ferrum-memory ||
|| ||
|| data stores: ||
|| Qdrant :6333 -- vector store (memories, episodes, KB embeddings) ||
|| SQLite -- episode records, eval scores, task_performance ||
|| Redis :6379 -- ephemeral session state, agent queues / pubsub ||
|| SQLite -- PersonalKB local index ||
||____________________________________________________________________________||
||
|| model calls, async compute, usage events, traces
||
______________________________________________________________________________
|| LAYER 1 -- INFERENCE, EXECUTION, AND BILLING ||
||____________________________________________________________________________||
|| ||
|| ferrum-gateway Rust ||
|| standalone service gateway, not only an agent gateway ||
|| generic core: HTTP routing, auth, rate/body limits, timeouts ||
|| streaming proxying, retries, circuit breakers, metrics, logs, traces ||
|| optional agent adapters: LLM fallback, budgets, MCP policy, metering ||
|| Ferrum fit: fronts axon, external LLMs, ferrum-mcp, HTTP upstreams ||
|| dependency boundary: core has no LLM, MCP, or Ferrum dependency ||
|| :8080 data plane / :8081 admin plane ||
|| ||
|| secure-agent-runner Rust ||
|| governed execution plane for agent, CI, MCP, and gateway jobs ||
|| RunJobRequest --> policy --> snapshot --> backend --> RunJobResult ||
|| local_process today; Firecracker design/skeleton for isolation ||
|| caps stdout/stderr/artifacts; stores request/result/snapshot/hashes ||
|| local is policy/replay only; Firecracker is the isolation target ||
|| :3000 HTTP API / agent-runner CLI ||
|| ||
|| axon Rust ||
|| production async AI inference server (HuggingFace Candle) ||
|| models: Llama, Mistral, SmolLM2 ||
|| dynamic request batching + SSE token streaming ||
|| three-tier fallback engine: GPU --> CPU --> deterministic stub ||
|| TurboQuant KV cache compression 7x lossless at 4-bit (ICLR 2026) ||
|| context window: ~2,000 tokens stock --> ~14,000 with TurboQuant ||
|| axon-native /v1/generate API :3000 (not yet OpenAI-compatible) ||
|| ||
|| ferrum-relay Rust ||
|| lightweight async HTTP relay for fetch and compute offload ||
|| clients: submit job --> receive job_id --> poll for result ||
|| handles concurrency, worker dispatch, result tracking ||
|| useful for Python agents, shell scripts, LLM tool wrappers ||
|| :3000 ||
|| ||
|| tokengate Rust ||
|| LLM token metering, cost tracking, and chargeback analytics ||
|| sits beside the app -- app still calls Anthropic/OpenAI directly ||
|| app reports usage to tokengate via REST ||
|| exact decimal arithmetic for sub-cent token prices ||
||____________________________________________________________________________||
||
|| shared contracts, primitives, sandbox patterns, infra PoCs
||
______________________________________________________________________________
|| LAYER 0 -- SHARED PRIMITIVES ||
||____________________________________________________________________________||
|| ||
|| ferrum-core Rust ||
|| unified FaError / FaResult across all Rust services ||
|| fixed-schema JSON logging: { ts, level, svc, msg } ||
|| OTLP span export via #[instrument_fa] (no HTTP framework dep) ||
|| published to crates.io v1.0.0 -- default-features = false ||
|| OTel collector :4317 / Jaeger UI :16686 ||
|| ||
|| forge-core Python ||
|| framework-agnostic domain layer below orchestration ||
|| shared tools, schemas, guardrails, Docker sandbox, eval wiring ||
|| portable: LangGraph OpenAI SDK CrewAI Google ADK AWS Strands ||
|| ||
|| nova-api-openstack Python ||
|| FastAPI + SQLite OpenStack VM lifecycle API ||
|| state-machine-driven transitions, structured operational logging ||
|| infrastructure control pattern proof of concept ||
||____________________________________________________________________________||
forge-agent -- one overnight session
______________________________________________________________________________
|| ||
|| 1. Read TASKS.md ||
|| || ||
|| V ||
|| 2. Build WorkspaceContext ||
|| ferrum-mcp/coding/glob --> list all repo files ||
|| ferrum-mcp/coding/grep --> find relevant symbols ||
|| ferrum-mcp/coding/read_file --> read key source files ||
|| axon (local model) --> summarize context cheaply ||
|| || ||
|| V ||
|| 3. Write failing test (TDD first) ||
|| Anthropic API claude-sonnet-4-6 --> generate test ||
|| ferrum-mcp/coding/write_test --> persist to disk ||
|| || ||
|| V ||
|| 4. Implement solution (max 3 attempts) ||
|| Anthropic API --> generate implementation ||
|| ferrum-mcp/coding/write_file --> write source ||
|| ferrum-mcp/coding/apply_patch --> or apply a diff ||
|| ferrum-mcp/coding/run_tests --> evaluate, compute reward ||
|| secure-agent-runner --> policy, snapshot, result hash ||
|| reward = 1.0 if all tests pass ||
|| || ||
|| V ||
|| 5. Commit ||
|| ferrum-mcp/coding/git_commit ||
|| || ||
|| V ||
|| 6. Log episode ||
|| ferrum-memory POST /experience ||
|| { task_id, tool_calls, test_result, reward, timestamp } ||
|| ferrum-evals: record ToolCorrectnessMetric for this session ||
|| || ||
|| V ||
|| 7. Repeat for next task in TASKS.md ||
|| ||
|| -------- when token budget expires or all tasks done -------- ||
|| ||
|| 8. Dream cycle (consolidation) ||
|| ferrum-memory GET /replay?strategy=prioritized&k=20 ||
|| Anthropic API: reflect on failure patterns across episodes ||
|| ferrum-memory POST /memory/store (distilled learnings) ||
|| Write DREAMS.md (human-readable, next Wake reads this) ||
|| ferrum-memory POST /session/close (consolidate working memory) ||
|| || ||
|| V ||
|| 9. Research data pipeline ||
|| ferrum-evals: compute BWT / FWT over all accumulated episodes ||
|| SQLite: append episode row to task_performance table ||
|| cl-experiments: queryable dataset --> arXiv preprint target ||
||____________________________________________________________________________||
______________________________________________________________________________
|| Service Port Protocol Consumed by ||
||____________________________________________________________________________||
|| ferrum-gateway 8080 HTTP proxy/data Web2 services, agents ||
|| 8081 admin/metrics operators, monitoring ||
|| fronts axon / MCP / LLM ||
|| secure-agent-runner 3000 HTTP + CLI ferrum-mcp sandbox/run ||
|| gateway / agents / CI ||
|| axon 3000 HTTP /v1/generate forge-agent (80% LLM) ||
|| ferrum-memory 8000 REST/JSON + FastAPI forge-agent ||
|| ferrum-agent ||
|| ferrum-evals ||
|| synapse in-proc embedded lib forge-agent ||
|| synapsed (opt) gRPC / HTTP / MCP ferrum-agent ||
|| cl-agent ||
|| taste-memory 8001 REST/JSON + FastAPI ferrum-agent planner ||
|| ferrum-evals 8002 REST/JSON + OTLP forge-agent ||
|| ferrum-agent reviewer ||
|| ferrum-mcp 3000 MCP stdio/SSE/HTTP forge-agent ||
|| ferrum-agent ||
|| native MCP clients ||
|| ferrum-relay 3000 REST/JSON Python agents ||
|| shell scripts ||
|| LLM tool wrappers ||
|| ferrum-agent 8003 REST + A2A + Events Operator UI ||
|| external agents ||
|| forge-agent 8004 REST (optional) ferrum-agent executor ||
|| tokengate -- REST/JSON any service using LLMs ||
|| Qdrant 6333 HTTP/gRPC ferrum-memory ||
|| taste-memory ||
|| PersonalKB ||
|| Redis 6379 Redis protocol ferrum-memory (sessions)||
|| ferrum-agent (queues) ||
|| OTel collector 4317 OTLP/gRPC all Rust services ||
|| Jaeger UI 16686 HTTP observability ||
||____________________________________________________________________________||