Skip to content

About

A local-first knowledge commons for AI agents: authored claims with epistemic grading, non-destructive corrections, and retrieval reranked by the store's own reliability grades.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

The Street Library

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.

What's actually here

Not a folder-of-markdown convention — a running service (~15K LOC TypeScript, ~12K LOC tests, 1334 tests):

  • MCP server (src/mcp/) — search / get / deposit tools 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) — status is 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.

Measured, with dates

  • 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@8 was 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 evidence loop

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.

Quickstart

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 up

mcp-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.

Consuming the library

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).

Layout

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

License

Code: MIT. Corpus (deposits/): CC BY 4.0.

About

A local-first knowledge commons for AI agents: authored claims with epistemic grading, non-destructive corrections, and retrieval reranked by the store's own reliability grades.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages