Why Vectorless?

Standard RAG pipelines require embedding models, vector databases, and GPU compute. The retrieval signal — cosine similarity — is a single opaque float that tells you nothing about why a document was returned. Locus takes a different path:

Six Retrieval Signals

Locus fuses six independent signals via Reciprocal Rank Fusion. Query intent is auto-classified and adjusts signal weights per query.

                        ┌───────────────────────────────────────────┐
  Query ──────────────► │  1. BM25          keyword ranking (BM25+) │
                        │  2. KG            entity expansion + hops  │
  Intent classifier     │  3. Link Walk     wikilink graph traversal  │
  ┌────────────────┐    │  4. Structural    date / tag / type match   │
  │ kg_first       │    │  5. Recency       freshness decay prior     │
  │ bm25_first     │    │  6. Link Popularity hub docs (inbound links)│
  │ balanced       │    └──────────────────────┬────────────────────┘
  └────────────────┘                           │
                                   Weighted RRF Fusion
                                               │
                              ┌────────────────▼──────────────────┐
                              │  Ranked chunks + provenance tags  │
                              │  bm25 · kg · link:hop1 · structural│
                              │  recency · link_pop               │
                              └───────────────────────────────────┘

Quick Start

pip install locus-rag

Index and retrieve in three commands:

# Index a directory of markdown files
locus index ./my-docs

# Retrieve — every result includes a provenance tag
locus retrieve "how does authentication work?"
# [1] auth/jwt.md  score=0.0421  via=bm25
#     JWT tokens are validated on every request. The token is...
# [2] auth/oauth.md  score=0.0318  via=kg
#     OAuth 2.0 flow for third-party integrations...

# Explain why a specific result was returned
locus explain <chunk_id> --query "authentication"
# {
#   "narrative": "Chunk from 'auth/jwt.md' (section: 'JWT Validation').
#                 Retrieved because: BM25: terms [jwt, authentication]
#                 appear in this chunk; KG: entity Alice links to this
#                 document via 3 KG triples.",
#   "bm25_matched_terms": ["jwt", "authentication"],
#   "kg_matched_entities": ["Alice"],
#   ...
# }

As a Python library:

from locus import LocusEngine

engine = LocusEngine(store_path=".locus")
engine.index("./my-docs")

chunks = engine.retrieve("JWT authentication flow", limit=5)
for chunk in chunks:
    print(f"{chunk.doc_path}  via={chunk.provenance}")
    print(chunk.content[:200])

# Explain a result
print(engine.explain(chunks[0].chunk_id, query="JWT")["narrative"])

As an MCP server (Claude Desktop / Claude Code / Cursor / Windsurf):

claude mcp add locus -- py -3 -m locus.mcp.server --store /path/to/.locus

Then ask Claude: "What does the codebase say about the auth system?" — Locus retrieves context, Claude answers.

Architecture

Locus is three layers — memory, retrieval, and interface — with no layer depending upward:

┌─────────────────────────────────────────────────────────────────┐
│  Interface Layer                                                  │
│  ┌────────────────┐  ┌──────────────────┐  ┌─────────────────┐  │
│  │  CLI (locus)   │  │  MCP stdio server│  │  HTTP JSON-RPC  │  │
│  │  26 commands   │  │  26 tools        │  │  POST /rpc      │  │
│  │                │  │  4 prompts       │  │  Bearer token   │  │
│  │                │  │  resources       │  │  CORS headers   │  │
│  └────────────────┘  └──────────────────┘  └─────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  Retrieval Layer                                                  │
│  BM25Retriever  ·  KGRetriever  ·  LinkWalker                    │
│  StructuralRetriever  ·  RecencyRetriever  ·  LinkPopularity     │
│  ──────────────────────────────────────────────────────────────  │
│  RRF Fusion  ·  QueryClassifier  ·  ContextBulletin              │
│  TokenBudget  ·  LocusCluster (multi-node)                       │
├─────────────────────────────────────────────────────────────────┤
│  Memory Layer                                                     │
│  Corpus         BM25 inverted index, checksum dedup, SQLite      │
│  TemporalKG     Triples + validity windows, traversal, match     │
│  EntityResolver Alias table → canonical entity names            │
│  Chunker        Section-aware (heading boundaries) + word-count  │
└─────────────────────────────────────────────────────────────────┘

All storage is SQLite — no external databases, no servers, no configuration.

Features

Retrieval

• Six-signal pipeline fused via weighted Reciprocal Rank Fusion
• Section-aware chunking — splits at # heading boundaries; long sections fall back to word-count
• Temporal retrieval — as_of="2024-01-01" returns only facts valid on that date
• Query intent routing — auto-classifies kg_first / bm25_first / balanced and shifts weights
• Checksum dedup — unchanged files never re-indexed; safe to run index on every startup

Knowledge Graph

• Prose triple extraction — 14 relation patterns (leads, works_at, is_a, part_of, replaced, depends_on...) auto-run during indexing — no annotation required
• Entity resolution — alias table maps name variants to canonical entities transparently
• Contradiction detection — surfaces same-predicate triples with different objects and overlapping validity windows
• BFS traversal — kg.traverse("Alice", max_depth=2) returns the full entity subgraph
• Pattern matching — kg.match("*", "works_at", "Acme") finds everyone at Acme; * is a wildcard
• KG export — GraphML (Gephi/Cytoscape), JSONL (scripting), DOT (Graphviz)

Explainability

engine.explain(chunk_id, query="authentication")
# {
#   "bm25_matched_terms": ["jwt", "authentication"],
#   "kg_matched_entities": ["Alice"],
#   "structural_matches": ["date 2025-02-10 in range Q1 2025"],
#   "kg_context": [{"entity": "Alice", "fact_count": 3, "sample_fact": "Alice --leads--> Auth team"}],
#   "narrative": "Chunk from 'auth.md'. Retrieved because: BM25: terms [jwt,
#                 authentication]; KG: Alice links to document..."
# }

This is structurally impossible with vector search. No cosine score has a "why."

MCP Integration

• 26 tools spanning retrieval, KG operations, bulletin management, cluster, evaluation, export
• MCP Resources — all indexed documents browsable as locus://doc/{path}
• 4 MCP Prompts — live-context templates pre-filled with retrieved knowledge before sending to the model
• HTTP transport — locus serve --port 7391 --token <secret> for remote clients

Memory Management

• Tiered bulletin board (Tier 0 Pinned / Tier 1 Hot / Tier 2 Archive) with hit-boost + age-decay scoring
• Persistent hot tier — bulletin.sqlite3 survives process restarts
• Soft token budget — WARNING / TREND / CRITICAL alerts; never blocks retrieval
• File watcher — locus watch ./docs auto-reindexes changes; deletions detected

Operations

• Health diagnostics — locus doctor checks corpus, KG, bulletin, store size, version
• Multi-node cluster — cross-corpus RRF fusion with node-prefixed provenance (jarv:bm25)
• OMPA bridge — direct import from OMPA vaults (identical SQLite KG schema)
• Evaluation — locus benchmark qa.json measures Recall@K and MRR

MCP Tools

MCP Prompts

Four templates rendered with live context before delivery to the model:

CLI Reference

locus [--store PATH] COMMAND [args]

Multi-node Cluster

Locus has first-class support for running multiple named nodes — each indexing a different knowledge domain — with cross-node retrieval fused via RRF.

from locus import LocusCluster

cluster = LocusCluster("cluster.json")
cluster.add_node("docs",    "/vaults/docs/.locus")
cluster.add_node("code",    "/vaults/code/.locus")
cluster.add_node("logs",    "/vaults/logs/.locus")

# Query all three simultaneously
chunks = cluster.retrieve("auth system deployment", limit=5)
for c in chunks:
    print(f"{c.provenance}  {c.doc_path}")
    # docs:bm25     auth/jwt.md
    # code:kg       src/auth/middleware.py.md
    # logs:recency  incidents/2025-02-auth-outage.md

Each result is tagged node_name:signal so you always know which knowledge base contributed which chunk. The registry persists across restarts — add a node once, always available.

OMPA Bridge

If you already use OMPA as your agent memory layer, Locus can import your vault directly. The KG schemas are identical — no transformation required.

locus ingest-ompa ~/path/to/ompa-vault --store .locus

from locus.bridge.ompa import OMPABridge
bridge = OMPABridge(engine, vault_path="~/ompa-vault")
result = bridge.ingest()
# {"chunks_indexed": 847, "triples_imported": 3_241, ...}

Markdown files are indexed via the normal pipeline. KG triples from .palace/knowledge_graph.sqlite3 are copied row-by-row. Safe to re-run — checksum dedup prevents duplicate indexing.

Health Diagnostics

locus doctor

Locus Doctor
============================================
[PASS]  corpus               47 docs | 203 chunks | avg 4.3 chunks/doc
[PASS]  knowledge_graph      1847 triples | 312 entities | 2 contradictions
[WARN]  bulletin             Tier 0 (pinned) is full — oldest entries will be demoted
[PASS]  entity_resolver      14 aliases registered
[PASS]  store_size           3.21 MB at .locus
[PASS]  version              Locus v0.6.0

Result: 5 pass  1 warn  0 fail

Benchmarking

Create a QA JSON file and run evaluation against your indexed corpus:

[
  {"query": "how does JWT authentication work?",    "expected_docs": ["auth/jwt.md"]},
  {"query": "incident response runbook",            "expected_docs": ["ops/ir.md"]},
  {"query": "Q1 2025 architecture decisions",       "expected_docs": ["adrs/q1-2025.md"]}
]

locus benchmark qa.json --k 1,3,5

Locus Benchmark
========================================
Queries:  20

Recall@1: 0.650  (13/20)
Recall@3: 0.800  (16/20)
Recall@5: 0.850  (17/20)
MRR:      0.723

Misses (top 5):
  [MISS] "incident response process" expected=['ir.md'] got=['deploy.md', ...]

KG Export & Visualization

locus export-kg knowledge.graphml   # Gephi / Cytoscape / yEd
locus export-kg knowledge.dot       # Graphviz → PNG/PDF
locus export-kg knowledge.jsonl     # scripting / grep

# Render a quick PNG with Graphviz
dot -Tpng knowledge.dot -o knowledge.png

Installation

pip install locus-rag

Zero runtime dependencies. Locus uses only Python stdlib: sqlite3, re, pathlib, threading, http.server, hashlib, math, json.

Optional extras:

pip install "locus-rag[ompa]"   # OMPA vault bridge
pip install "locus-rag[dev]"    # pytest, coverage

Requirements: Python 3.11+

Contributing

See CONTRIBUTING.md. All contributions welcome — bug reports, feature requests, PRs.

git clone https://github.com/jmiaie/locus
cd locus
pip install -e ".[dev]"
pytest tests/ -v

License

MIT — see LICENSE.

Acknowledgements

Locus is architecturally descended from OMPA (Obsidian-MemPalace-Agnostic), which pioneered the three-layer vault → palace → KG design for agent memory. The tiered bulletin board, temporal KG schema, and session lifecycle patterns are direct adaptations. The OMPA bridge enables seamless import of existing OMPA vaults.