BaseMouse

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

npm test
npm run lint
npm run eval:retrieval
npm run eval:retrieval:demo
npm run dev

Open:

http://localhost:3000
http://localhost:3000/agent-governance-demo.html
http://localhost:3000/design-partner.html
http://localhost:3000/compare.html

Useful endpoints:

GET    /healthz                          (liveness, process-only)
GET    /readyz                           (readiness; 200 + degraded:true in demo-fallback mode)
GET    /api/repository?limit=&offset=    (paginated; anonymous sees the public demo corpus)
GET    /api/search?q=agent%20context
GET    /api/search?q=agent&type=feature
GET    /api/context-pack?q=memory&limit=3
GET    /api/context-pack?tag=memory
GET    /api/billing/config
POST   /api/checkout
POST   /api/documents                    (requires Authorization: Bearer bm_...)
GET    /api/documents/:id                (current revision, workspace-scoped)
PUT    /api/documents/:id                (optimistic lock: expectedVersion or If-Match)
PUT    /api/documents/:id?mode=upsert    (idempotent: created/updated/unchanged — no version needed)
DELETE /api/documents/:id                (tombstone — history preserved)
GET    /api/documents/:id/history
GET    /api/usage                        (plan, documents, pack pulls, storage vs limits)
POST   /api/keys/claim                   (exchange a paid checkout session for a key — shown once)
POST   /api/keys/rotate                  (authenticated; old key dies immediately)
POST   /api/billing/portal               (authenticated; Stripe-hosted cancel/payment management)
POST   /api/stripe/webhook               (Stripe events; SDK-verified signature)
GET    /claim?session_id=...             (post-checkout claim page, five designed states)

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.

# issue a design-partner key (run via kubectl exec, never from a workstation)
DATABASE_URL=... node scripts/issue-key.mjs --plan demo

# import a folder of markdown into your workspace
BASEMOUSE_API_KEY=bm_... node scripts/import.mjs ./docs --base-url https://basemouse.com

# post-deploy smoke check
node scripts/smoke.mjs --base-url https://basemouse.com

# apply migrations (CI does this automatically before deploy)
DATABASE_URL=... node scripts/migrate.mjs

The round trip (write a doc, watch an agent cite it)

# 1. write a document into your workspace
curl -s -X POST https://basemouse.com/api/documents \
  -H "Authorization: Bearer $BASEMOUSE_API_KEY" -H "Content-Type: application/json" \
  -d '{"id":"release-policy","title":"Release Policy","body":"Never deploy on Fridays.","type":"policy"}'

# 2. pull a context pack that cites it — note the checksum and version
curl -s "https://basemouse.com/api/context-pack?q=release+policy" \
  -H "Authorization: Bearer $BASEMOUSE_API_KEY" | head -40

# 3. the record is append-only — edit it, then ask for the history
curl -s https://basemouse.com/api/documents/release-policy/history \
  -H "Authorization: Bearer $BASEMOUSE_API_KEY"

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:

claude mcp add --transport http basemouse https://basemouse.com/mcp \
  --header "Authorization: Bearer bm_..."

Unauthenticated POST /mcp returns 401 with WWW-Authenticate so Cursor marketplace Connect starts OAuth. Paste an existing bm_ key on the consent page, or continue with the public demo. Config-file clients still send Authorization: Bearer bm_.... REST anonymous demo is unchanged. The endpoint is tool-agnostic: node integrations/cli/basemouse.mjs register prints ready-to-paste MCP config for Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI, Grok CLI, AWS Kiro, and Google Antigravity — and SSE-only clients like IBM Bob via the mcp-remote bridge, which basemouse register bob emits.

Sync your workspace (any platform, any coding tool)

New here? docs/getting-started.md maps your situation to the right import path (coding workspace vs. any Markdown folder vs. GitHub repo) — the sync CLI below is tailored to the AI-coding-workspace layout (CLAUDE.md/PROGRESS.md per project); for arbitrary Markdown use scripts/import.mjs instead.

integrations/cli/basemouse.mjs is a zero-dependency Node CLI that keeps a projects workspace synced into BaseMouse as project:<slug>-tagged, versioned documents. Node-only — no bash/curl/jq — so it behaves identically on Windows, macOS, and Linux:

# one-shot: push every project's CLAUDE.md/PROGRESS.md under ~/projects
BASEMOUSE_API_KEY=bm_... node integrations/cli/basemouse.mjs sync

# continuous: reconcile once, then auto-push a project the moment its docs are saved
BASEMOUSE_API_KEY=bm_... node integrations/cli/basemouse.mjs watch

# one project directory (what CI uses)
BASEMOUSE_API_KEY=bm_... node integrations/cli/basemouse.mjs sync --single . --slug myproject

# MCP config for your coding tool (claude|cursor|windsurf|codex|gemini)
node integrations/cli/basemouse.mjs register

# the CLAUDE.md "Context retrieval" block for a project
node integrations/cli/basemouse.mjs snippet myproject

Sync is idempotent and cheap: one PUT ?mode=upsert per doc — the server decides created/unchanged/updated next to its own normalization (no client-side comparison to drift), merges tags additively so tags you added elsewhere are never destroyed, and an unchanged save writes nothing. Per-doc failures warn and continue (empty stub files are skipped, not failed, so CI stays green). Requires Node 20+ and a server with upsert support (basemouse.com, or self-hosted at the D9 release or later — older servers get a clear upgrade message). Override BASEMOUSE_BASE_URL for self-hosted, --base-dir/BASE_DIR for a different workspace root.

Sync on git push (GitHub Action)

For the most hands-off setup, let sync ride on git push — no daemon, no per-machine key, works from any OS/editor. Add the repo secret BASEMOUSE_API_KEY, then in .github/workflows/basemouse-sync.yml:

name: basemouse-sync
on:
  push:
    branches: [main]
    paths: ['CLAUDE.md', 'PROGRESS.md']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: basemouse/basemouse-core/integrations/github-action@master
        with:
          api-key: ${{ secrets.BASEMOUSE_API_KEY }}

The action syncs the repo's CLAUDE.md/PROGRESS.md tagged project:<repo-name> (override with the slug input; base-url targets a self-hosted instance).

integrations/claude-code/basemouse-integration.sh (bash) is deprecated in favour of the CLI — it still works, but only receives fixes.

Operations

GET /metrics exposes Prometheus-format counters (pack pulls, quota denials, claims, degraded state). Set ALERT_WEBHOOK_URL (ntfy/Slack) and the app pages you when degraded mode persists >5m or claim failures spike. The OpenAPI spec lives at /api/openapi.json.

GET /healthz reports liveness plus non-secret deployment posture: billing and meshai enablement and a license object (mode, tier, whether a license key is present, expiry). The license key value is server-only and never appears in any response.

Faceted filters

Both /api/search and /api/context-pack accept optional type and tag query parameters:

• type — case-insensitive match against the document type (concept, feature, experience, principle, note, policy).
• tag — case-insensitive match against a document's tags.

Empty parameters are treated as "no filter". A value longer than 256 characters returns 400 { "error": "invalid_filter", "message": "..." }.

Both endpoints echo the applied filters back in a filters field, e.g. "filters": { "type": "feature", "tag": null }. For context packs the filter is applied to the candidate set before the limit, so totalMatches and truncated reflect the post-filter count.

GET /api/search?q=agent&type=feature  ->  only feature-type results
GET /api/context-pack?tag=memory      ->  pack entries all tagged "memory"

Example context-pack shape:

{
  "schema": "basemouse.context_pack.v1",
  "query": "memory",
  "filters": { "type": null, "tag": null },
  "entryCount": 1,
  "totalMatches": 1,
  "truncated": false,
  "citations": [
    {
      "id": "memory-capsules",
      "label": "[memory-capsules] Memory Capsules v1"
    }
  ],
  "entries": [
    {
      "id": "memory-capsules",
      "links": ["agent-context-engine", "ghost-doc"],
      "relevance": { "score": 3, "matchedTerms": ["memory"] },
      "related": [
        { "id": "agent-context-engine", "title": "Agent Context Engine", "inPack": true },
        { "id": "ghost-doc", "title": null, "inPack": false }
      ],
      "provenance": {
        "source": { "kind": "seed", "path": "data/seed/memory-capsules.json" },
        "checksum": "..."
      }
    }
  ],
  "relationships": [
    { "from": "memory-capsules", "to": "agent-context-engine", "resolved": true },
    { "from": "memory-capsules", "to": "ghost-doc", "resolved": false }
  ]
}

Billing / Stripe setup

BaseMouse renders paid Starter, Team, and Enterprise plans from /api/billing/config. POST /api/checkout creates a Stripe Checkout Session for self-serve tiers when Stripe is configured. If the env vars are absent, the UI and API degrade to a clear contact-sales state; no payment or customer data is stored locally.

Environment variables:

CHECKOUT_ENABLED        # Master switch for self-serve Stripe checkout (required to enable paid tiers)
STRIPE_SECRET_KEY       # server-only restricted key (rk_ preferred; sk_ also works)
STRIPE_WEBHOOK_SECRET   # endpoint signing secret from Stripe → Webhooks
STRIPE_PRICE_STARTER    # Stripe recurring Price ID for Starter
STRIPE_PRICE_TEAM       # Stripe recurring Price ID for Team
STRIPE_PUBLISHABLE_KEY  # optional public key for future Stripe client surfaces
STRIPE_API_VERSION      # optional; defaults to the pinned app version
APP_BASE_URL            # optional; defaults to https://basemouse.com for checkout return URLs
BILLING_SUCCESS_URL     # optional explicit Checkout success URL
BILLING_CANCEL_URL      # optional explicit Checkout cancellation URL
BILLING_CONTACT_URL     # optional mailto/CRM URL for Enterprise/contact-sales fallback
STRIPE_PRICING_TABLE_ID # optional public ID reserved for future pricing table embed

To take real payments:

1. In Stripe, create a product with recurring monthly prices, tagging each price with tier metadata (starter or team). The app matches tiers by that tag, not by price ID order.
2. Create a webhook endpoint pointing at /api/stripe/webhook and copy its signing secret into STRIPE_WEBHOOK_SECRET.
3. Set the variables above in the server environment along with CHECKOUT_ENABLED=true. Never commit them. For local development put the same names in .env (see .env.sample).
4. Verify /api/billing/config shows checkout-enabled tiers without exposing any secret, and that /api/stripe/webhook accepts Stripe test events.

A restricted key (rk_…) is preferred over a secret key. The minimum scopes are write on Checkout Sessions and Billing Portal Sessions, plus read on Checkout Sessions for the claim verification path.

Checkout arms itself once STRIPE_SECRET_KEY and at least one price ID are present, and degrades to a contact-sales state when they are absent, so a deployment with no Stripe configuration still runs.

Seed documents

Seed documents live in:

data/seed/*.json

Each document is normalized by src/store.js, gets deterministic provenance metadata, and receives a stable 16-character SHA-256 checksum from the normalized content.

Deployment

The hosted service runs on Kubernetes and deploys continuously from main: a build pushes the image, migrations run against the production database, and the cluster rolls out the new revision. Self-hosters can deploy the same image with the Docker Compose examples in deployment/compose/ (see docs/self-hosted.md).

Set CANONICAL_HOST to your bare domain (e.g. example.com) if you serve the same site on both the apex and www. hostnames: GET and HEAD requests arriving on www.<CANONICAL_HOST> are then 308'd to the bare host, so crawlers index one origin instead of two. Only GET and HEAD are redirected, so the POST traffic that carries every API, MCP, and webhook call is never moved. Leave it unset to disable the redirect entirely — that is the default.

Key docs

• docs/getting-started.md — first calls against the API and MCP endpoint
• docs/agent-integration.md — wiring BaseMouse into agents and MCP clients
• docs/client-libraries.md — JavaScript and Python API clients
• docs/retrieval-eval.md — golden-query retrieval quality harness
• docs/demo-corpus-agent-governance.md — public Agent Governance Demo corpus, page, and eval baseline
• docs/self-hosted.md — run BaseMouse + local LLM + Slack inside a company network

Product thesis

The repository that agents actually love.

Shipped today:

• Agent Context Engine — structured/versioned basemouse.context_pack.v1 exports
• retrieval: lexical + faceted + graph-aware linking + metadata, with citations and provenance
• hybrid retrieval — opt-in retrieval=hybrid blends one-hop graph expansion over document links, lexical term overlap, and a local hashed-vector similarity, with per-result signal explanations (lexical / vector / graph). Vectors are local/offline hashed-feature embeddings (no external vector DB, no paid embedding API), toggled with BASEMOUSE_VECTOR_RETRIEVAL.
• retrieval quality harness — npm run eval:retrieval scores search and context-pack output against strict golden-query suites; the seed suite is a smoke test and partner-corpus suites are the next quality gate.
• local-first / self-hosted privacy
• append-only history & audit trail

Vision / roadmap (not implemented yet — listed as direction, not claims):

• real-corpus retrieval eval suites (human-reviewed expected docs, CI quality gates) before further retrieval tuning
• semantic vector retrieval (today's vectors are local hashed-feature embeddings — shared-vocabulary overlap in a dense space, not a learned semantic model; a real embedding provider can be plugged into the same vector path)
• full GraphRAG (multi-hop traversal + learned embeddings over the relationship graph; today's hybrid mode is one-hop graph expansion plus local hashed vectors)
• memory capsules
• built-in agent sandbox
• precision canvas UX

MeshAI integration (OpenTelemetry)

BaseMouse emits a standard OTLP/HTTP trace span for every context pack it generates, so MeshAI (or any OpenTelemetry backend) can observe, attribute, and audit what context agents pull. The wire format is vendor-neutral OTLP, so the same emission also works with Datadog, Honeycomb, or Grafana Tempo.

It is disabled by default and is a no-op until configured. No document bodies are ever sent: spans carry retrieval evidence only (query, counts, document ids).

Configure via environment variables:

MESHAI_OTLP_ENDPOINT   # e.g. https://api.meshai.dev/api/v1/ingest (no-op if unset)
MESHAI_API_KEY         # MeshAI API key (msh_...) with the telemetry:write scope
MESHAI_SERVICE_NAME    # optional, defaults to "basemouse"
MESHAI_OTLP_TIMEOUT_MS # optional, defaults to 3000

Spans are POSTed to ${MESHAI_OTLP_ENDPOINT}/v1/traces with a Bearer token. Each /api/context-pack request emits one span named basemouse.context_pack with service.name, gen_ai.system=basemouse, gen_ai.operation.name=context_pack, and basemouse.* evidence attributes. Emission is fire-and-forget with a hard timeout: if MeshAI is slow or down, the context pack is still returned normally.

GET /healthz reports whether the integration is configured ("meshai": true).