Local-first frontier (Locus)
Principles (hard)
- Less dependency — default path must not require cloud APIs, vector DBs, or ML npm wheels
- Zero config —
npx @sylphx/locus --root=…works offline with local BM25 - Local first, cloud optional — embeddings / remote providers only when user configures them
- Speed / size / performance — prefer single native MCP binary; avoid dual full stacks
- Rust first — MCP + retrieval engine native; fail-closed without TS stdio fallback
- Simple but powerful — one primary agent tool:
codebase_search
What is true today (evidence)
| Layer | Status | Evidence |
|---|---|---|
| MCP default | Rust-first | bin/locus launches native locus-mcp-server; no TS stdio fallback |
| Zero-config search | Yes | Local BM25 over regex symbol chunks; no API key |
| Package size (MCP) | ~10 MB unpacked | primarily staged native locus-cli + locus-mcp-server |
TS core @sylphx/coderag | Overweight vs principle | hard deps include @huggingface/transformers, @ai-sdk/openai, ai, drizzle-orm, @libsql/client, plus many @sylphx/synth-* optionalDeps |
| Cloud optional | Partial | OpenAI / HF present as library deps even when MCP path does not need them |
Target architecture (Final Decision direction)
Agent ──MCP──► locus (native rmcp) ──► locus-cli (Rust BM25, regex symbol chunks)
│
SDK (optional thin) ──► same Rust engine OR pure-Rust crate bindings
│
Optional cloud ── only if user sets provider config (peer/optional dep)Non-negotiable targets
- MCP install path remains zero-config, local BM25, no API key.
- SDK package must not force HF transformers / OpenAI SDK on every install:
- move
@huggingface/transformers,@ai-sdk/openai,ai, LanceDB to optionalPeers or a separate@sylphx/locus-vectorpackage - keep pure index/search SDK thin (or document “MCP-only recommended”)
- move
- One concept: find the right code chunk with path/line evidence — not architecture graph (that is Spine).
- One public tool lead:
codebase_search(engine aliases internal only). - Size: prefer platform optionalDependencies for natives (Citra pattern) over shipping multi-arch blobs in one tarball when possible; keep install path simple.
Peer anchors (learn, do not clone)
| Peer | What to absorb | What not to become |
|---|---|---|
| 100% Rust codegraph MCP peers | Native graph/search speed; few tools; SQLite local | 14+ vanity tools; LLM-required summaries as authority |
| Cloud RAG stacks | Hybrid quality when configured | Default Docker/vector DB tax |
| grep/ripgrep | Speed + zero deps | Literal-only results |
Zero-config usage (canonical)
bash
npx -y @sylphx/locus --root=/absolute/path/to/project
# tool: codebase_search { "query": "auth login", "limit": 5 }Honest residual / progress
- MCP path is local-first (Rust).
- SDK hard deps slimmed (2026-08-01):
@huggingface/transformers,@ai-sdk/openai, andaiare optionalDependencies; default tokenizer is pure local simple code tokenizer. - OpenAI embeddings / LanceDB / HF StarCoder2 remain opt-in when packages are installed and configured.
- Remaining hard deps: local SQLite path (
@libsql/client,drizzle-orm), watcher,ignore,@sylphx/synth(+ optional language packs). - Brand/transitional version skew may exist during expand–contract; see PUBLISH.md.