HoloAbsorb — Sovereign Codebase Intelligence Skill

Working directory: C:/Users/Josep/Documents/GitHub/HoloScript (MANDATORY)

HoloAbsorb is the umbrella; GEV is its consumer spine

HoloAbsorb is the official product identity. The absorb skill name, @holoscript/absorb-service, absorb-service, and existing tools stay stable compatibility contracts. GEV = Graph + Embedding + Vector/RAG is the consumer spine, not the whole product. Discover the executable ownership map with holo_absorb_manifest({}) or holoscript holoabsorb --json.

Codebase queries flow through these core lanes:

• Graph — CodebaseGraph + community detection (structure, call/import edges)
• RAG — GraphRAGEngine fuses 0.6·semantic + 0.2·connections + 0.2·impact and synthesizes with an LLM (sovereign HoloLlama by default — see below)
• Embedding — EmbeddingIndex over sovereign HoloEmbed vectors by default
• Vision — CodebaseSceneCompiler / HoloEmitter emit a navigable graph.holo

HoloAbsorb also owns ingest/cancellation, sovereign transport and cache authority, synthesis, self-improvement/GRPO, the thin hosted service boundary, and paper/benchmark evidence.

Judge results at the service level (embed + graph re-rank + synthesis), never one pillar alone — weak embedding-only recall is by-design, the graph fixes precision (W.764).

Route to the sovereign LOCAL MCP — the remote is FS-blind (R.027)

The #1 reason agents "battle" absorb: their MCP client routes codebase tools to the remote holoscript server (railway / holoscript.net, cwd=/app), which cannot see your local files → cache_root_mismatch / "No Graph RAG engine initialized". For any local repo, call the holoscript-local MCP (tools appear as mcp__holoscript-local__*) — see the /holoscript-local skill. The remote handles only shared state (board, knowledge, seats) and public-repo lanes. If you just rebuilt the dist, restart the MCP client before calling it (W.766 — a live stdio server loses its content-hashed chunks when the dist is rebuilt underneath it).

For several agents, prefer one supervised Streamable HTTP service at http://127.0.0.1:7411/mcp. Every client then reuses one warm in-memory graph instead of spawning a worker and graph state per task. The maintainer ecosystem keeps this service durable with node scripts/local-service-supervisor.mjs recover holoscript-local-mcp.

If an agent reports Transport closed:

1. Probe http://127.0.0.1:7411/health. A healthy response proves the graph service, not the agent host's cached MCP handle.
2. Recover the durable service if health is down. Current Codex/Grok proxy leases self-heartbeat while their client pipe is open, so message inactivity or a competing fresh smoke connection must not evict a healthy conversation transport.
3. If a handle was already closed before that liveness repair, reconnect/reload the MCP host once. If the host cannot reattach in the current task, use holoscript graph-status, holoscript query, or holoscript impact-analysis. These commands call the same canonical Absorb handlers and workspace cache directly. They are a transport-independent degradation path, not a second raw repo scanner.

When to Use This Skill

Absorb turns any codebase into a queryable knowledge graph with semantic search, call-chain tracing, community detection, impact analysis, and LLM-powered Q&A. It supports TypeScript, Python, Rust, Go, and JavaScript via tree-sitter adapters.

Use absorb when you need to:

• Understand before changing — scan the codebase, ask "what calls X?", check blast radius before refactoring
• Find by meaning, not name — semantic search finds "authentication handler" even if the function is called resolveRequestingAgent
• Ask natural language questions — Graph RAG combines vector search + graph traversal + LLM synthesis for cited answers
• Detect drift — fast content-hash check to see if the graph cache is stale without re-scanning
• Trace cross-package flows — follow a call chain from studio through core to mcp-server across package boundaries
• Find dead code — discover exported symbols with zero callers, orphaned interfaces, unused compiler targets
• Run self-improvement — L0 (code fixer) → L1 (strategy optimizer) → L2 (meta-strategist) autonomous improvement pipeline
• Generate .holo visualizations — emit navigable 3D compositions of the codebase graph for spatial exploration

Do NOT use absorb for:

• Git history questions → use git log, git blame
• Runtime behavior → absorb sees static structure, not runtime values
• Deployment config → absorb scans source code, not .env or Docker files
• Simple file reads → use Read tool directly if you already know the path

Covered tools

The capability cartographer uses this section to verify that absorb prefix coverage is backed by explicit tool names.

absorb_query, absorb_diff, absorb_list_projects, absorb_create_project, absorb_delete_project, absorb_run_absorb, absorb_run_improve, absorb_run_pipeline, absorb_run_query_ai, absorb_run_render, absorb_check_credits, absorb_provenance_answer, absorb_typescript, absorb_suggest_holoscript_transform, absorb_get_status, absorb_fmu

Official umbrella and lifecycle routes: holo_absorb_manifest, holo_cancel_absorb, holo_visual_graph_context.

Quick Start

# 1. Check graph freshness (always do this first)
# MCP: holo_graph_status({})
holoscript graph-status

# 2. Scan if stale (>24h or never scanned)
# MCP: holo_absorb_repo({ directory: ".", force: false })
holoscript absorb .

# 3. Query the graph
# MCP: holo_query_codebase({ query: "callers", symbol: "buildIndex" })
holoscript query "what calls buildIndex"

Production Endpoints

Auth: ABSORB_API_KEY from ~/.ai-ecosystem/.env (source via canonical pattern). Admin/founder tier = all tools free, no rate limits.

MCP Tools — FREE (Local, No Credits)

Codebase Scanning

Graph Queries

Semantic Search & RAG

Project Management (Studio)

MCP Tools — PAID (Studio, Credits Deducted)

Credit Costs (from pricing.ts — authoritative)

1 credit = $0.01. LLM tokens metered at 15% markup.

Pipeline Stages

Local Scan (holo_absorb_repo)

scan (CodebaseScanner + language adapters)
  → graph (CodebaseGraph + community detection)
    → embed (EmbeddingIndex: HoloEmbed sovereign default | Xenova offline | OpenAI/nomic opt-in | BM25 floor)
      → cache (~/.holoscript/workspaces/<workspace-id>/graph-cache.json + embeddings)
        → emit (.holo scene | JSON graph | stats)

Phases: queued → scanning → analyzing → indexing → complete

Self-Improvement Pipeline (L0/L1/L2)

ABSORB → DIAGNOSE → GENERATE → VALIDATE → COMMIT → LEARN

• L0 Code Fixer: patches, measures quality delta
• L1 Strategy Optimizer: adjusts focus, profile, budget
• L2 Meta-Strategist: generates skills, wisdom entries, architectural insights

CLI Commands

# Absorption
holoscript absorb .                              # Scan → .holo output
holoscript absorb packages/core --json           # JSON knowledge graph
holoscript absorb . --for-agent                  # Agent manifest
holoscript absorb . --depth shallow              # Fast manifest-only
holoscript absorb . --since HEAD~5               # Changed files only

# Semantic query
holoscript query "what calls buildIndex"                    # BM25 default
holoscript query "how does the parser work" --with-llm      # LLM synthesis
holoscript query "find auth handlers" --provider openai     # Cloud embeddings
holoscript query "trace from absorb" --top-k 20 --json      # Machine-readable

# Self-improvement
holoscript self-improve                          # 5 cycles default
holoscript self-improve --cycles 10 --commit     # Auto-commit fixes (uses canonical scopes, 72-char limit)
holoscript self-improve --daemon                 # Continuous until convergence

Embedding Provider — Sovereign HoloEmbed by default (F.106 / D.118 / W.GOLD.005)

The default is sovereign HoloEmbed — native, zero-cost, no key, no egress (@holoscript/holoembed, 768-dim). Do NOT reach for OpenAI or nomic by reflex; foreign vectors are opt-in, never the silent default. The embedding space is the sovereignty boundary (W.763): once the graph/memory is indexed with HoloEmbed vectors, a foreign provider's vectors are not comparable to it — mixing them silently corrupts recall.

Weak embedding-only recall is BY DESIGN, not a defect (W.764 / D.123). HoloEmbed's natural-language recall on embeddings alone is lower than a giant cloud model (R@1 ~40% vs nomic ~81%). That is expected and fine — GEV never retrieves on embeddings alone. GraphRAGEngine re-ranks candidates with graph signal, and the graph is what makes precision good. Never judge (or "fix") retrieval by swapping in a foreign embedder.

Provider tiers (sovereign first):

1. holoembed — native @holoscript/holoembed, the default; $0, offline, no key
2. xenova — local WASM transformer, offline fallback
3. bm25 — keyword-only floor; correct for exact-symbol lookups, weak for semantic
4. openai / nomic — foreign, opt-in ONLY via explicit EMBEDDING_PROVIDER=openai; use only for a deliberate cross-model comparison, never as the ambient default

If a foreign provider is active unexpectedly: unset EMBEDDING_PROVIDER / OPENAI_API_KEY in the shell so the service falls back to sovereign HoloEmbed. Re-index if foreign vectors leaked into a HoloEmbed graph — the two spaces are not queryable together.

Example Questions for Graph RAG (holo_ask_codebase)

Graph RAG is NOT keyword search. It embeds your question, finds semantically similar symbols, walks the call graph to discover callers/callees/communities, scores by impact radius, then feeds the enriched context to an LLM for a cited answer. This means questions about relationships and flow outperform questions about names.

The engine sees: symbol signatures, doc comments, file paths, import edges, call edges, community clusters, and transitive impact. It does NOT see: runtime values, environment variables, deployment config, or git history. Frame questions accordingly.

Compilation & Target Pipeline

• "Walk me through what happens when compile_to_unity is called — from .holo parse through AST transform to target output emission"
• "What sovereign compilers exist vs bridge compilers, and how does CompilerBase enforce RBAC before either type runs?"
• "How does the incremental compiler determine which symbols are stale and need recompilation vs which can be skipped?"
• "Which compilers share the most code — are there compilation families that could be refactored into shared base classes?"
• "What happens to trait metadata during the WebGPU compilation path — does it survive or get stripped?"
• "How does the multi-target compiler coordinate when the same .holo source is compiled to 3 targets simultaneously?"

Trait System & Composition

• "Trace how a trait defined in constants/physics.ts flows through AST construction, composition resolution, compiler consumption, and R3F rendering"
• "What trait categories have custom runtime handlers vs categories that are purely declarative metadata?"
• "Show the composition chain when an object has both 'grabbable' and 'physics_body' — how are conflicts resolved?"
• "Which traits are spatial-only vs applicable to non-visual domains like banking or legal compliance?"
• "How does trait validation prevent incompatible combinations, and what error does an agent see when it fails?"

Simulation & Scientific Computing

• "How does the structural FEA solver dispatch WebGPU compute shaders — trace from SimulationContract through solver selection to GPU kernel launch"
• "What is the difference between TET4 and TET10 element formulation and where does the shape function evaluation happen?"
• "How does the thermal solver couple with the structural solver for thermo-mechanical analysis — is it one-way or bidirectional?"
• "Where does the SNN spiking neural network store neuron state between timesteps on the GPU, and how does it handle the 10K neuron @ 60Hz budget?"
• "What validation does the V&V pipeline run on simulation results — how does it detect solver divergence?"

MCP Server & Tool Infrastructure

• "Trace how a tool definition in tools.ts gets wired to its handler — through http-server.ts dispatch, the cascadeHandled pattern, and back to the response"
• "How does the HoloMesh board tool authenticate differently from compile tools — what's the auth flow for each?"
• "What happens when an MCP tool call arrives via JSON-RPC (POST /mcp) vs REST (POST /api/compile) — where do the paths diverge and reconverge?"
• "How do agent-orchestration-tools coordinate multi-tool workflows — is there a DAG scheduler or is it sequential?"
• "Where does the observability pipeline export OpenTelemetry traces and what spans does it capture for a tool call?"

Plugin Architecture

• "What interface must a domain plugin implement to register with the core — trace from plugin discovery through to trait injection"
• "How does the medical-plugin's DICOM trait differ from the radio-astronomy FITS trait — do they share any base infrastructure?"
• "Can plugins define their own compilation targets or only inject traits that existing compilers consume?"
• "What's the plugin loading mechanism — are they statically imported or discovered at runtime via package.json entries?"

Identity, Auth & Agent Coordination

• "Trace resolveRequestingAgent through all three resolution paths: key registry, legacy agent store, and raw env key comparison"
• "What's the difference between founder auth, agent auth, and per-server keys — how does scope enforcement work for each?"
• "How does the CRDT sync layer handle conflicting edits from two agents writing to the same scene simultaneously?"
• "What does the team-coordinator do when an agent misses two heartbeat cycles — is the task released immediately or is there a grace period?"

Debugging & Investigation

• "What error recovery paths exist in the compiler dispatch chain — where can compilation fail silently?"
• "Where are WebGPU compute shaders dispatched in the SNN package, and what happens if the GPU doesn't support the required features?"
• "How does the embedding index handle out-of-vocabulary tokens that OpenAI's tokenizer hasn't seen?"
• "What validation runs before a .holo file reaches any compiler — is it parser-level, semantic-level, or both?"
• "Why might the SSE transport fail on Railway specifically — what CDN behavior causes GET/POST routing to split?"

Edge Cases (where Graph RAG beats naive search)

• "Which exported functions have zero callers anywhere in the codebase?" — find dead code
• "There are multiple 'parse' functions — which handles .holo vs .hs vs .hsplus?" — disambiguate naming collisions
• "Which tool handlers are registered dynamically at startup vs statically in tools.ts?" — runtime vs static structure
• "What code paths only execute in production (Railway env) vs development?" — env-gated behavior
• "Which packages use workspace:* dependencies that would break for external users?" — monorepo gotchas
• "If I delete packages/connector-github, what's the total transitive impact?" — blast radius at scale
• "Find interfaces that are defined but never implemented" — orphaned contracts
• "Which test suites import the most source files?" — slow test candidates

Tricky Framing (same question, better results)

Semantic Search (holo_semantic_search)

• "authentication handler" — find auth-related code
• "database connection" — find DB logic
• "error recovery" — find error handling patterns
• "trait composition" — find trait system code
• "WebGPU compute" — find GPU compute shaders
• "spatial indexing" — octree, BVH, spatial hash
• "animation interpolation" — keyframe and easing logic
• "credit deduction" — billing and metering

Filter for precision:

• holo_semantic_search({ query: "compiler", type: "class" }) — only compiler classes
• holo_semantic_search({ query: "validate", type: "function" }) — only validation functions
• holo_semantic_search({ query: "shader", file: "snn-webgpu" }) — only SNN GPU code

When Results Are Wrong

Workflow: Before Refactoring

1. holo_graph_status({})
   → Is cache fresh (<24h)? If not, continue to step 2.

2. holo_absorb_repo({ directory: ".", force: false })
   → Builds/refreshes knowledge graph (~21ms from cache, ~3-10s fresh)

3. holo_impact_analysis({ files: ["src/compiler/SceneIRCompiler.ts", "src/compiler/SceneIRTsxEmitter.ts"] })
   → Shows all transitively affected files

4. holo_query_codebase({ query: "callers", symbol: "CompilerBase" })
   → Lists everything that depends on the symbol

5. Refactor with confidence — you know the blast radius.

Workflow: Codebase Q&A

1. holo_graph_status({})  → ensure graph is loaded

2. holo_ask_codebase({
     question: "How does the trait registration pipeline work?"
     // llmProvider defaults to sovereign HoloLlama (D.117):
     // detectDefaultLLMProvider() ?? 'holollama' — llama.cpp llama-server at :18080.
     // Omit it to stay sovereign; pass 'anthropic'/'openai' only for a deliberate override.
   })
   → Returns synthesized answer with file citations

3. Follow citations to read specific files for deeper understanding.

Workflow: Recursive Self-Improvement

1. holo_graph_status({})  → ensure fresh graph

2. absorb_run_pipeline({ projectId: "...", layer: "l0" })
   → L0: scans → diagnoses → generates patches → validates → commits

3. absorb_run_pipeline({ projectId: "...", layer: "l1" })
   → L1: adjusts strategy based on L0 results

4. absorb_run_pipeline({ projectId: "...", layer: "l2" })
   → L2: generates new skills and architectural insights

Key Rules

• ROUTE LOCAL: for local repos, use the holoscript-local MCP (mcp__holoscript-local__*), never the FS-blind remote holoscript (R.027)
• STAY SOVEREIGN: HoloEmbed embeddings + HoloLlama synthesis by default; foreign OpenAI/nomic/anthropic are explicit opt-in only (F.106 / D.117 / D.118)
• ALWAYS call holo_graph_status before any scan or query operation
• NEVER use force: true on holo_absorb_repo unless holo_graph_status says cache is corrupt
• RECOVER after rebuild: shared HTTP and supervised stdio processes recover independently; only a host that already cached a closed handle needs a host reconnect (W.766)
• Cache TTL: 24 hours. Incremental re-scan detects changes via git content hashes.
• Cost awareness: Free tools for local ops. Paid tools deduct credits. Check with absorb_check_credits.
• Graph cache: one mutable local lane per physical workspace under ~/.holoscript/workspaces/<workspace-id>/ (or the equivalent Docker cache root). Set HOLOSCRIPT_CACHE_LAYOUT=flat only for explicit legacy compatibility; unrelated repos and temporary scans must not share a writable graph or embedding cache.

Source Files Reference