Add connected knowledge cache design doc

[Saga4]

Core Reasoning:
2b4cd92

Summary

• Adds a design draft for Locality as a local connected knowledge cache, not only a mount tool.
• Frames the missing-URL problem and proposes loc context build as the workflow-first primitive for agents.
• Separates locate, resolve, target hydration, context hydration, and agent run as measurable phases.
• Documents architecture concepts, CLI/Desktop implications, roadmap, risks, and guardrails.
• Adds research/inspiration notes covering Glean, Obsidian, Notion API search limits, MCP, RAG, GraphRAG, SQLite FTS5, and Tantivy, plus deliberate non-goals.

Validation

• Docs-only change.
• Verified the new markdown file uses ASCII-only content.
• No build or test run required.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
locality	Ready	Preview, Comment	Jul 22, 2026 5:37pm

[github-actions]

Codex review

• major - experiment/agent-conversation-profile.mjs:805: shellToolGroupFor now returns per-subcommand groups like loc_status and loc_diff, but the existing profiler test still asserts the old aggregate bash_loc group and folded stack names. This will fail once the test can run in a normal writable temp environment. Minimal fix: update experiment/agent-conversation-profile.test.mjs expected summaries/folded stacks for the new grouping, or preserve bash_loc if that aggregate name is still the intended contract.

• major - experiment/locality-mcp-comparison/scripts/run-natural-retrieval-batch.mjs:21: LOC_BIN is computed but never exposed to the spawned Codex run, while the Locality strategy prompt tells the agent to run bare loc. The documented runner only adds $HOME/.cargo/bin to PATH, so environments where the repo build exists at target/debug/loc but no installed loc is on PATH will make loc search/status/diff fail or silently turn the Locality strategy into files-only. Minimal fix: validate LOC_BIN, pass it through, and either prepend dirname(LOC_BIN) to the spawned PATH or instruct the prompt to use $LOC_BIN; add a smoke test that sets LOC_BIN to a non-PATH stub.

Verification: node --check passed for the new .mjs scripts. I could not run the profiler tests end-to-end in this sandbox because /tmp is read-only, causing mkdtemp to fail before assertions.