Forge Architecture & Specs
160+ MCP actions for autonomous AI development. A dedicated AI orchestration layer plans and executes agent work. Tree-sitter WASM extracts symbols from TypeScript/JavaScript/Python/Go/Rust. AI breaks issues down into sub-tasks automatically. Self-healing atomic counter (GREATEST pattern) ensures issue IDs never collide.
Performance & MCP Tool Metrics
MCP Tool Response
<100ms p95 (simple actions)
Semantic Search
<200ms for 100k documents (pgvector)
AST Symbol Extraction
<50ms per file (Tree-sitter WASM)
Session Checkpoint
<500ms snapshot + serialize
Issue ID Generation
Self-healing atomic counter (GREATEST pattern)
Concurrent AI Agents
50+ per tenant
Knowledge Classification
category (6 types) + free-text tags + memory type (L1 always-load facts/preferences, L2 contextual discoveries/events/advice)
Blast Radius Simulation
<1s for 10k-file codebase
1. The MCP Forge Tool Registry (160+ Actions)
| Action | Description |
|---|---|
| `get_session_handoff` | Full project brief: active sprint, velocity, workload, agent memory |
| `checkpoint_session` | Snapshot current progress for safe interruption |
| `cleanup_stale_sessions` | Mark idle sessions completed, free resources |
| `get_session_context` | Raw session data for resume |
| `break_session` | Force-terminate a session |
| Action | Description |
| -------- | ------------- |
| `list_projects` | All projects accessible to the agent |
| `get_project` | Project details (accepts UUID or key e.g. PLAT) |
| `create_project` | New project with auto-generated key |
| `update_project` | Update name, description, github repo |
| `delete_project` | Archive a project |
2. Self-Healing Issue ID Generation
Issue creation uses a self-healing atomic counter to generate issue identifiers (e.g., PLAT-123):
sql
UPDATE forge_projects
SET counter = GREATEST(
COALESCE(counter, 0),
COALESCE(
(SELECT MAX(
CAST(SUBSTRING(fi.identifier FROM POSITION('-' IN fi.identifier) + 1) AS INTEGER)
)
FROM forge_issues fi
WHERE fi.project_id = forge_projects.id
AND POSITION('-' IN fi.identifier) > 0),
0
)
) + 1
WHERE id = ${project.id}
RETURNING counter
Why this pattern:
- Race condition safe: Uses
UPDATE ... RETURNINGin a single statement - Self-healing:
GREATESTensures the counter never falls behind actual max identifiers—even if DR restored issue rows without the counter - Backstop retry: A unique-constraint violation triggers exactly one reconcile-and-retry pass before propagating the error
- No gap vulnerability: No reliance on sequence gaps from rolled-back transactions
3. Tree-sitter AST Indexer
| Field | Description |
|---|---|
| `name` | Symbol identifier |
| `kind` | class, function, interface, type, constant, enum |
| `lineStart` / `lineEnd` | Source location |
| `signature` | Full function/type signature |
| `docstring` | JSDoc / docstring text |
| `calls` | Functions called by this symbol |
4. Semantic Embedding Engine
| Action | Purpose |
|---|---|
| `generate_embeddings` | Batch-embed all knowledge entries for a project |
| `reingest_changed` | Re-embed only entries modified since the last pass (safe to schedule daily) |
| `semantic_search_knowledge` | Find knowledge entries by meaning via the configured AI gateway |
| `embed_symbols` | Embed indexed code symbols (hash-idempotent, budgeted per call) |
| `semantic_code_search` | "Find the function that throttles login attempts" — over embedded symbols |
| `check_knowledge_freshness` | Three detectors: code drift (structural fingerprint), unverified age (90d), never-accessed |
5. Agent Memory & Session Checkpoints
Session Structure:
Every agent session tracks: a unique session and agent ID, the project it's scoped to, status (active / completed / failed / paused), start time and last-heartbeat timestamp, the current task, a serialized checkpoint of in-progress work, and running lists of discoveries and learnings captured along the way.
Checkpoint Flow:
- Agent calls
checkpoint_sessionwith serialized progress - Session state persisted durably
- Heartbeat updated; sessions idle for 7+ days (configurable) →
cleanup_stale_sessionsmarks them completed - Next agent retrieves context via
get_session_handoff
File Locking (Concurrency Control):
- Agents claim files via
claim_file_lock(30-min TTL, up to 8h) - An in-memory registry tracks each claim's holder and timestamp
- Locks auto-expire after TTL;
release_file_lockclears explicitly - Prevents concurrent agents from editing the same file
typescript
// Example: Start a development sessionconst handoff = await aeion.forge({ action: "get_session_handoff", projectId: "proj_abc123"});// handoff includes:// - project: { name, key, description }// - activeSprint: { name, velocity, capacity, issues[] }// - agentWorkload: { assigned, inProgress, completed }// - recentDiscoveries: { title, content, relevance }[]// - sessionTimeline: { agent, task, duration }[]
// Example: Create issue with inline todosconst issue = await aeion.forge({action: "create_issue",projectId: "proj_abc123",title: "Implement user authentication",type: "story",priority: "high",description: "Add JWT-based auth flow with refresh tokens",items: ["Design auth flow diagram","Implement token service","Add unit tests","Update API docs"]});// issue.id, issue.identifier ("PLAT-42"), issue.items[]
// Example: AI breakdown of a story into sub-tasksconst breakdown = await aeion.forge({action: "breakdown_issue",id: "PLAT-42"});// breakdown.subtasks[] = [{ title, description, estimatedHours }]
// Example: Semantic code searchconst results = await aeion.forge({action: "semantic_search_knowledge",query: "authentication middleware patterns",projectId: "proj_abc123",limit: 5});// results.entries[] with similarity scores
// Example: Bug capture from errorconst bug = await aeion.forge({action: "create_bug_from_error",projectId: "proj_abc123",errorTrace: "TypeError: Cannot read property 'id' of undefined...",filePath: "src/auth/service.ts",commitHash: "a3f9c2d"});// bug.duplicateOf = existing issue ID if detectedBefore making cross-cutting changes (e.g., renaming a shared utility), agents call `simulate_blast_radius` with file paths or a symbol name. Symbol mode walks the resolved call graph inbound (depth 2) to list every affected symbol with its distance, folds their files into the registry dependency analysis, and cross-references active agent sessions for collision warnings.
Tree-sitter extracts each symbol's callee names at index time; `resolve_symbol_edges` turns names into real edges with an honesty rule that keeps the graph trustworthy: a same-file definition wins, a project-unique definition is accepted, and ambiguous names (think `setup`, `handler`) are skipped _and counted_ — a misleading edge is worse than no edge. The graph re-resolves automatically per file after every reindex, powering transitive-caller answers and symbol-level blast radius.
A nightly consolidation pass per project chains the memory lifecycle: re-embed changed knowledge → code-aware staleness (entries snapshot a structural fingerprint of the files they describe — a gotcha whose code was rewritten is stale no matter how recent) → contradiction scan → promotion mining → stale-session cleanup → decision-assumption checks. The result persists as a Memory Health report your next session briefing renders inline, every problem line naming the action that fixes it.
`create_knowledge`, `capture_learning`, and `promote_diary_to_knowledge` check for near-duplicates BEFORE writing — semantic similarity when embeddings are live, stopword-filtered token overlap otherwise — and refuse with the matches, a reconciliation hint, and a `force:true` escape hatch. When a text AI is configured, the closest match also gets a contradiction verdict so agents reconcile instead of stacking conflicting guidance.
Every open issue knows its topological impact: closing it unblocks N issues worth M points, computed transitively over the blocks-graph (cycle-guarded). `get_unblocked_tasks` sorts by leverage, `suggest_sprint` packs priority → leverage → age, and the session briefing calls out the highest-leverage pick.
`log_decision` accepts `assumptions: [{text, files?, knowledgeIds?}]`. Referenced files snapshot a structural fingerprint at decision time; the nightly pass flags decisions whose premises drifted (code rewritten, knowledge deprecated) so a plan can't rot silently. `validate_adr_compliance` judges diffs against stated assumptions, not just decision prose. Unverifiable assumptions are honestly marked `manual_review` — never pretended-checked.
`complete_issue` enforces a resolution-hygiene gate: non-epic closes require a `verificationMethod` plus linked evidence (an attached commit or PR). `attach_commit` with the commit's file list feeds a self-building commits→files→issues graph that sharpens `route_incoming_bug` and prior-work recall with every shipped ticket; `reconcile_commits` backfills evidence from git history idempotently and never auto-closes anything.
`calculate_critical_path` traverses issue dependencies (blocks/blocked_by links) to identify the chain of issues that will delay the release. Returns the minimum viable release timeline and which issues are on the critical path vs. parallelizable.
`audit_codebase_smells` runs a heuristic analysis over the file registry — fan-in, fan-out, and change frequency — to flag architectural smells with mathematical metrics rather than an LLM's guess: **god files** (extremely high fan-in and fan-out), **high-churn tight coupling** (high fan-out on a frequently-changed file), and **possible orphans** (zero fan-in but depends on others). Results are returned as a ranked list, not auto-filed as issues.
`validate_adr_compliance` checks a proposed code diff against existing Architecture Decision Records. The diff is parsed for architectural signals (new dependencies, API surface changes, data model changes) and matched against ADR scope fields. Returns compliance status and references to relevant ADRs.
`find_cross_project_insights` searches the shared knowledge base for entries tagged across multiple projects. Useful for finding patterns (e.g., "we've solved distributed caching 3 times for different modules—can we unify?"). Also surfaces shared technical debt that spans projects.
Forge hosts the **Meta-Compiler** — a visual canvas at `/forge/meta-compiler`. Rather than hand-writing a TypeScript class to add a new language target to the [Universal AST Engine](/architecture/universal-ast-engine), engineers compose one visually: a `Language Definition` node, state-variable nodes, AST node `case` blocks, and template-literal mappings. "View Compiler Code" emits a ready-to-register `LanguageGenerator` class — immediately available on the visual canvas. It's the extensibility seam of the AST engine: the platform's **31 built-in compilation targets** (PyTorch, GLSL, Solidity, IFC/BIM, eBPF, zk-SNARK, G-Code, MAVLink, FFmpeg, WebGPU, and more) are an open-ended set rather than a fixed list — a compiler that writes compilers.