basemouse/basemouse-core

**Domain:** basemouse.com
**GitHub org:** https://github.com/basemouse
**Status:** live (paid plans)
**Version:** v0.3
BaseMouse is an AI-native document/notes repository for workspaces and agents: a local-first knowledge base that exports structured, versioned context packs agents can actually use.
What's in this repo
This is a small zero-dependency Node.js app:
- durable in-repo seed repository in data/seed/*.json
- /api/repository endpoint with count + normalized documents
- /api/search?q=... search endpoint with scores and matched terms
- /api/context-pack?q=...&limit=... agent-ready basemouse.context_pack.v1 export
- Faceted retrieval filters type and tag on both /api/search and /api/context-pack
- retrieval=lexical|hybrid mode on both endpoints (lexical is the default, fully back-compatible). hybrid blends three signals — lexical term overlap, one-hop graph expansion along document links, and a local vector similarity — and annotates every result with a per-signal retrieval block explaining *why* it surfaced. The vector signal uses **local, offline hashed-feature embeddings** built in Node (no external vector DB, no paid embedding API, no network); it is honest token-overlap-in-a-dense-space, not a semantic model. Disable it with BASEMOUSE_VECTOR_RETRIEVAL=off (graph+lexical hybrid still works).
- context-pack citations, provenance, document versions, checksums, relevance, truncation, and agent instructions
- graph-aware relationships: each entry carries its outbound links and a resolved related list, plus a pack-level relationships edge list, so agents can follow how documents connect
- safer static file serving with path containment, nosniff headers, malformed URL handling, and API validation/limits
- web UI for search, context-pack generation, raw JSON inspection, copy, and download
- public Agent Governance Demo page at /agent-governance-demo.html, showing
the synthetic governance corpus, sample auditor/operator queries, and the
lexical vs hybrid retrieval-quality baseline
- public Design Partner Intake page at /design-partner.html, asking for one
small real corpus, real questions, and a concrete agent workflow to benchmark
- public alternatives/comparison page at /compare.html, covering the five
things people use instead of BaseMouse and where BaseMouse is the wrong tool
- JSON-LD structured data (Organization, WebSite, SoftwareApplication, FAQPage)
on the homepage, pinned to src/billing.js and the visible FAQ by
test/structured-data.test.js so the markup cannot drift from the product
- lightweight JavaScript and Python API clients in clients/ (see docs/client-libraries.md)
- Slack Socket Mode connector for local LLM + BaseMouse grounding in integrations/slack/
- Dockerfile plus self-hosted Docker Compose examples in deployment/compose/ (see docs/self-hosted.md)
- retrieval quality eval harness (npm run eval:retrieval) with golden queries in data/retrieval-eval/
- GitHub Actions workflow for test/build/push on main
Local development
Open:
Useful endpoints:
Write API and persistence
With DATABASE_URL set (managed Postgres — Supabase), BaseMouse runs a durable
store: API keys scope private workspaces, writes are append-only revisions, and
the public demo corpus survives database outages by degrading to the in-repo
seeds (X-BaseMouse-Degraded: true). Without DATABASE_URL the app runs the
in-memory seed store exactly as before. Provide DATABASE_CA_CERT (PEM) when
the provider's server cert chains to a private CA — TLS verification is never
disabled.
The round trip (write a doc, watch an agent cite it)
MCP (connect your agent natively)
BaseMouse speaks the Model Context Protocol at POST /mcp (stateless
Streamable HTTP, JSON-RPC). Tools: search, get_context_pack, and
upsert_document (the write door — agents can persist decisions and session
context by stable id, idempotently; unchanged content writes nothing) — same
auth, scoping, and quota metering as REST. Claude Code: