A local-first knowledge commons for AI agents. Like a Little Free Library: take a book, leave a
book — when an agent digs something up the hard way, it deposits the distilled finding so the next
agent (or the same one next week) reads it in one call instead of repeating the excursion. What
distinguishes it from the memory frameworks it superficially resembles: deposits are authored
claims with epistemic grading (confidence, authority, durability, inline
[fact]/[likely]/[reported] markers), corrections are non-destructive (supersede chains and
conflict edges, never overwrite), and retrieval is reranked by the store's own reliability grades
— relevance × confidence × freshness. Wrong costs more than absent here, and the system is built
around that asymmetry. See docs/POSITION.md for where this sits against Mem0, Letta,
Zep/Graphiti, and friends.
Not a folder-of-markdown convention — a running service (~15K LOC TypeScript, ~12K LOC tests, 1334 tests):
- MCP server (
src/mcp/) —search/get/deposittools over HTTP with bearer auth, scopes, rate-limiting, and telemetry. Disk is the source of truth; the server boots and serves degraded disk-only mode even with the search index down. - Hybrid search (
src/search/) — Meilisearch BM25 + TEI embeddings (bge-small-en-v1.5), client-side rerank over a bounded candidate window with inspectable constant multipliers. Superseded items are hidden; stale ones are demoted and badged. - Artifact pipeline (
src/artifact/) — content-addressed capture (inline, file, or SSRF-guarded URL fetch up to streaming gigabyte scale), then OCR/extraction in a sandboxed container (--network none, read-only root, caps dropped) with a stage-then-promote trust boundary. - Derived lifecycle (
src/index/derive.ts) —statusis computed from supersede/conflict/ deprecation edges and freshness decay, never authored. Writing it is rejected. - Integrity & ops — read-only
fsck(src/fsck/), blue-green index rebuild + swap, git-sync of the corpus, Prometheus metrics with file-backed job gauges, alert rules and dashboards (observability/), and a scheduled retrieval canary (streetlib canary) because the one thing a search system must not do is regress silently — a claim the canary itself failed to honour on its first production deployment (#22), which is in the log rather than glossed. - Capture reflex (
src/capture/,src/commands/review.ts) — a session-end hook proposes candidate deposits from an agent transcript and a review queue drains them. Machine capture proposes; a human promotes. The caps are structural (tier: candidate,authority: observed, confidence capped, lineage edges stripped) and the false-positive rate is measured rather than asserted (docs/CAPTURE_HOOK.md). - CLI (
streetlib,src/cli.ts) — deposit, search, capture, reindex, fsck, cards, canary, git-sync, review, propose, and the rest; 22 commands.
- Hybrid recall@8 0.909 vs lexical 0.500 (MRR 0.87 vs 0.36) on the live corpus, 2026-06-25. The same run caught four bugs unit tests structurally miss.
- Both recorded misses were diagnosed (answer text past the embedding window) and fixed by chunking long learnings, 2026-08-18: seed-corpus recall@8 0.773 → 0.818 in an isolated verification stack, with the truncation miss recovered.
- 2026-08-20 — the number above went backwards, and the gate passed it green. The uplift shipped
a default retrieval mode far worse than the one it replaced: default-hybrid recall@1 0.182
against lexical's 0.409.
recall@8was the one metric on which the broken build won (0.818 vs 0.636), and it was the only metric the gate read (#24, #25). - 2026-08-21, current — after calibrating the embedder score distribution and re-pinning the gate
on rank-sensitive metrics: default-hybrid recall@1 0.864, recall@3/@8 1.000, MRR 0.932,
lexical baseline unchanged at 0.409 / 0.636 / 0.636 / 0.508. Reproduce with
npm run eval.
Every number here is dated and none is retired. The 2026-06-25 figure is kept beside the regression
that followed it because a benchmark you can only see at its best is a marketing artifact; the
harness (scripts/recall-harness.ts) is in-repo and release-gating, and the run that caught the
regression is the same one that publishes these.
The rarest thing this repo publishes is not a feature — it's the record of how the system behaves
under real agent use. docs/usage/ exports the full issue log: 24 real
issues with reconstructible evidence (exact queries, ids, scores, dates), including a
session-length case study and entries for what
worked (recorded as do-not-fix). docs/ROADMAP_SOA_2026-08.md grades every
proposed item by its evidence — [incident] / [workaround] / [measured] / [foresight] — and
keeps decision lines for what was accepted, deferred, and why.
docs/ops/GATE_P_CHECKLIST.md records the publication-hygiene pass.
cp docker/.env.example docker/.env
openssl rand -base64 32 # → MEILI_MASTER_KEY in docker/.env
# mint an MCP token: MCP_AUTH_TOKENS={"<secret>":{"scopes":["read","write"],"label":"local-dev"}}
docker compose -f docker/compose.yml upmcp-server comes up at http://localhost:8730 (serving disk-only degraded mode until Meilisearch
is healthy, then full hybrid search — it self-heals an empty index on startup):
curl http://localhost:8730/healthz
curl -X POST http://localhost:8730/mcp \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"meilisearch"}}}'The full runbook — OCR profile, reindex recipes, smoke tests — is in docker/README.md. The production stack for this deployment (Traefik routing, SOPS-managed secrets, ofelia cron jobs, pinned image digests) is site-specific and is not part of this repo's published tree.
Agents connect over MCP (search/get/deposit). Two pieces make consumption reliable rather
than hopeful:
- skills/street-library/SKILL.md — the client-side discipline: how to query (sweep the subsystem's vocabulary, not your frame), how to weigh graded hits, when a miss is a deposit prompt, and how to file problems back.
- CARDS.md — generated per-collection cards (a few hundred tokens each) meant to live in
a consumer's always-on context. They carry no facts — only enough scent to trigger the search
reflex. Regenerated with the index projections (
streetlib cards).
deposits/ the corpus — one authored claim per file, provenance frontmatter
src/ the service (mcp, search, deposit, artifact, index, fsck, metrics, commands)
docker/ local dev stack
observability/ alert rules + Grafana dashboards
scripts/ recall harness, canary cases, ingest harness + demo corpus
docs/ design, position, roadmap, build log, usage narrative (issue-log export)
skills/ the consumer-side skill file
INDEX.md CARDS.md derived projections (generated, tracked)
- docs/DESIGN.md — the spec: invariants, data flows, threat model, resolved conflicts
- docs/POSITION.md — where this sits in the agent-memory field, claim by claim
- docs/VISION_2026.md — the original June 2026 vision, preserved unchanged; everything it deferred as "worth adding the day it bites" got built, and that distance is part of the story
- docs/TASKS.md — the build log, milestone by milestone
- docs/CAPTURE_HOOK.md — installing the session-end capture hook: what it sends, what it caps, and how to measure its false-positive rate before trusting it
- Runbooks: docs/ops/M2_RUNBOOK.md (runtime), docs/ops/M5_AUTH_RUNBOOK.md (auth/keys), docs/ops/M5_DR_RUNBOOK.md (restore drill), docs/ops/M5_BACKUP_POLICY.md