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