Skip to content

Local-first frontier (Locus) ​

Principles (hard) ​

  1. Less dependency — default path must not require cloud APIs, vector DBs, or ML npm wheels
  2. Zero config — npx @sylphx/locus --root=… works offline with local BM25
  3. Local first, cloud optional — embeddings / remote providers only when user configures them
  4. Speed / size / performance — prefer single native MCP binary; avoid dual full stacks
  5. Rust first — MCP + retrieval engine native; fail-closed without TS stdio fallback
  6. Simple but powerful — one primary agent tool: codebase_search

What is true today (evidence) ​

LayerStatusEvidence
MCP defaultRust-firstbin/locus launches native locus-mcp-server; no TS stdio fallback
Zero-config searchYesLocal BM25 over regex symbol chunks; no API key
Package size (MCP)~10 MB unpackedprimarily staged native locus-cli + locus-mcp-server
TS core @sylphx/coderagOverweight vs principlehard deps include @huggingface/transformers, @ai-sdk/openai, ai, drizzle-orm, @libsql/client, plus many @sylphx/synth-* optionalDeps
Cloud optionalPartialOpenAI / 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 ​

  1. MCP install path remains zero-config, local BM25, no API key.
  2. 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-vector package
    • keep pure index/search SDK thin (or document “MCP-only recommended”)
  3. One concept: find the right code chunk with path/line evidence — not architecture graph (that is Spine).
  4. One public tool lead: codebase_search (engine aliases internal only).
  5. 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) ​

PeerWhat to absorbWhat not to become
100% Rust codegraph MCP peersNative graph/search speed; few tools; SQLite local14+ vanity tools; LLM-required summaries as authority
Cloud RAG stacksHybrid quality when configuredDefault Docker/vector DB tax
grep/ripgrepSpeed + zero depsLiteral-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, and ai are 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.

Released under the MIT License.