Lumos

Why it exists

Ask an AI agent to change a large, unfamiliar Laravel app and it burns context blindly grepping files — and still misses the routes, model relations, and call chains that matter. Lumos pre-computes that structure once and hands an agent a precise context bundle per task, so it implements changes grounded in how the program actually fits together. It’s my personal answer to “how do I make AI agents genuinely competent on real production code?”

The retrieval, done properly

• AST symbol-level chunking. A chunk is a whole function / method / type — carrying its fully-qualified name, params, return type, docstring, side-effects, and real call-graph edges — not a fixed-size text window. This is the difference between RAG over blobs and RAG over a program’s semantics.
• Hybrid retrieval in one database. ParadeDB gives pgvector (HNSW cosine) and BM25 in a single Postgres. Lumos runs both, fuses them with Reciprocal Rank Fusion (k=60), then expands one hop through the call graph to pull in callers/callees that pure similarity missed. No separate Elastic or Qdrant.
• Framework-aware. A Laravel enrichment pass models routes → controllers → models → tables, jobs, events, policies, and tags side-effects (db read/write, http, mail, queue) — so queries like “trace this endpoint” actually work.

The agentic layer

A spec becomes a task DAG; agents claim tasks from a leased queue with heartbeats, each calling get_task_context to assemble the bundle (spec requirements, dependency artifacts, repo-map signatures, semantic hits, target-file state, stale-code warnings). Exposed as ~50 MCP tools. A built-in eval harness scores retrieval (Recall@5/10, MRR) and A/Bs embedding providers.

Built on a plugin kernel with enforced invariants — exclusive schema ownership, no cross-plugin imports, ≤500 LOC/file — a codebase deliberately architected so an agent can understand any feature by reading one folder. Personal, local-only; a study in building systems for AI agents.