hybridmind AGENTS.md

HybridMind — agent entry point

Updated: August 2026. Read top to bottom before changing anything; it is short on purpose. README.md is the human-facing front door; this file is the working contract for anyone editing the code.

What this is

HybridMind is a local dense + sparse + graph retrieval service for AI-memory experiments: FastAPI over an authoritative SQLite store, with FAISS HNSW, BM25/BM25S, and NetworkX indexes derived from it. It is built to show what it retrieved, why, and whether that evidence helped.

It is not a transformer KV-cache replacement and not a validated 10M–100M-token context system. Those are preregistered research targets governed by docs/RETRIEVAL_RESEARCH_PROTOCOL.md. Do not let claims drift: the honest-status table is PHASE_IMPLEMENTATION_STATUS.md, and the research evidence ledger is docs/research/design-space-experiment-program.md.

Cold start

.\.venv\Scripts\Activate.ps1            # .venv only, never system Python
pip install -r requirements.txt         # pnpm only inside memorybench/
pytest tests/ -q                        # full offline suite (~400 tests, zero provider calls)
python -m compileall -q main.py config.py api engine storage models cli sdk mcp_server scripts benchmarks tests verify

• The offline suite makes zero provider calls. If your change needs one, see rule 5 below first.
• make test / make compile wrap the same checks (make verify runs the legacy opt-in suite separately).
• API: python -m uvicorn main:app --host 127.0.0.1 --port 8000. Startup does not wake remote providers by default.
• Arriving mid-stream? Read docs/CURRENT_STATE.md (and update it when you finish; see Covenants).

Load-bearing map (do not break casually)

Path	Role	Breakage radius
config.py	Single configuration source of truth	Every subsystem reads it; add fields here, never raw os.getenv
storage/sqlite_store.py	Authoritative store (SQLite/WAL), bitemporal fields	Schema/write-path changes need migration thinking
storage/vector_index.py, bm25_index.py, graph_index.py	Derived rebuildable indexes	Must stay rebuildable-from-SQLite; never authoritative
storage/mindfile.py	.mind snapshot publish/restore validation	Security-sensitive path/checksum/semantic gates
engine/hybrid_ranker.py	Candidate generation, temporal filtering, RRF fusion, optional rerank stages	Retrieval semantics + measured numbers depend on exact behavior
engine/fusion.py	RRF implementation (k=60, weight validation)	Fusion contract
engine/embedding.py, provider_policy.py	Remote-only native 4096-d embeddings; endpoint-bound keys	Fail-closed contract, rule 3/4
engine/llm_client.py (+ llm.py, runpod_llm.py)	Centralized LLM policy chain	Provider routing/spend discipline
main.py + api/*.py	App assembly, security middleware, routers	Auth/rate/limit logic lives in main.py ASGI middleware
eval_ledger.py, eval_common.py, eval_stats.py, eval_*.py	Evaluation ledgers, prompts, statistics	Recorded numbers must stay interpretable/comparable
scripts/preflight.py	Default-deny live-provider admission gate	Spend safety
memorybench/src/providers/hybridmind/index.ts	Benchmark harness provider (gitignored tree; these two files tracked)	Contract test: experiments/harnesses/memorybench_provider_contract.test.ts