basemouse-core

BaseMouse is an AI-native document/note repository, intended for workspaces and AI agents, positioned as a local-first knowledge base that can export structured, versioned, agent-ready context packs. This repository, basemouse-core, is its open-source core, a zero-dependency Node.js application.

Purpose BaseMouse is designed to provide agents with shared, versioned memory: agents can search the knowledge base, obtain context packs with citations and checksums, and persist decisions and session context through write interfaces. It is suited to scenarios where multiple agents or workspaces need to share the same traceable source of knowledge.

Main capabilities

• The repository has built-in seed data (data/seed/*.json), and provides an /api/repository endpoint that returns document counts and normalized documents.
• The search endpoint /api/search?q=... returns search results with scores and matched terms.
• The context pack endpoint /api/context-pack?q=...&limit=... exports the agent-ready basemouse.context_pack.v1 format.
• Both endpoints support facet filtering: the type and tag parameters (case-insensitive, empty parameters are treated as no filtering, and over 256 characters returns a 400 error), and echo the applied filters.
• Retrieval modes: lexical (default, fully backward compatible) and hybrid. hybrid blends three signals—lexical term overlap, one-hop graph expansion along document links, and local vector similarity—and labels each result with the retrieval block for each signal, explaining why it appears. The vector signal uses Node's built-in local offline hashed feature embedding (no external vector database, no paid embedding API, no network); it is essentially term overlap in a dense space, not a semantic model; it can be disabled with BASEMOUSE_VECTOR_RETRIEVAL=off (graph + lexical hybrid remains available).
• Context packs include citations, provenance, document versions, checksums, relevance, truncation information, and agent instructions.
• Graph-aware relationships: each entry carries outbound links and a resolved related list, as well as a pack-level relationship edge list, making it easy for agents to trace document connections.
• Safer static file serving: path containment, nosniff headers, malformed URL handling, API validation, and limits.
• The Web UI supports search, context pack generation, raw JSON inspection, copying, and downloading.
• Public Agent Governance Demo page (/agent-governance-demo.html), showcasing synthetic governance corpus, example audit/action queries, and lexical and hybrid retrieval quality baselines.
• Public Design Partner Intake page (/design-partner.html), soliciting small real corpora, real questions, and specific agent workflows for benchmarking.
• Public alternatives/comparison page (/compare.html), covering five ways people replace BaseMouse and scenarios where BaseMouse is not suitable.
• The homepage includes JSON-LD structured data (Organization, WebSite, SoftwareApplication, FAQPage), and is pinned via tests to src/billing.js and the visible FAQ to prevent markup drift.
• The clients/ directory provides lightweight JavaScript and Python API clients (see docs/client-libraries.md).
• integrations/slack/ provides a Slack Socket Mode connector for local LLM + BaseMouse grounding.
• deployment/compose/ provides a Dockerfile and self-hosted Docker Compose example (see docs/self-hosted.md).
• Retrieval quality evaluation tooling (npm run eval:retrieval), with golden queries located in data/retrieval-eval/.
• GitHub Actions workflow for test/build/push on the main branch.

Usage Local development: run the zero-dependency Node.js app and use the API endpoints above.

Write API and persistence: after setting DATABASE_URL (managed Postgres — Supabase), BaseMouse runs persistent storage: API keys are scoped to private workspaces, writes are append-only revisions, and the public demo corpus degrades to the in-repo seed on database failure (X-BaseMouse-Degraded: true). When not set,when DATABASE_URL is not set, the app runs in-memory seed storage. When the provider server certificate chains to a private CA, DATABASE_CA_CERT (PEM) must be provided; TLS verification is never disabled.

MCP connection: BaseMouse provides Model Context Protocol at POST /mcp (stateless Streamable HTTP, JSON-RPC). Tools include search, get_context_pack, and upsert_document (the write entry point — agents can idempotently persist decisions and session context via stable ids; if the content is unchanged, no write occurs), using the same authentication, scopes, and quota metering as REST. See the official documentation for a Claude Code configuration example. An unauthenticated POST /mcp returns 401 with WWW-Authenticate, so that Cursor marketplace Connect can initiate OAuth. You can paste an existing bm_ key on the consent page, or continue using the public demo. Configuration-file clients still send Authorization: Bearer bm_.... The REST anonymous demo is unchanged. The endpoint is tool-agnostic: node integrations/cli/basemouse.mjs register can print ready-to-use MCP configurations for Claude Code, Cursor, Windsurf, Codex CLI, Gemini CLI, Grok CLI, AWS Kiro, and Google Antigravity, as well as for SSE-only clients bridged via mcp-remote (such as IBM Bob).

Syncing workspaces: integrations/cli/basemouse.mjs is a zero-dependency Node CLI that syncs projects workspaces as versioned documents tagged project:<slug>. It requires only Node, with no bash/curl/jq, and behaves consistently across Windows, macOS, and Linux. Syncing is idempotent and low-cost: one PUT ?mode=upsert per document, the server decides create/unchanged/update alongside its own normalization, tags are merged incrementally, and unchanged saves do not write. A single document failure warns and continues (empty stub files are skipped rather than failing). RequiresRequires Node 20+ and a server that supports upsert (basemouse.com or self-hosted D9 version and later). The self-hosted address can be overridden via BASEMOUSE_BASE_URL, and the workspace root directory via --base-dir / BASE_DIR.

Sync via git push (GitHub Action): add the repository secret BASEMOUSE_API_KEY, then configure it in .github/workflows/basemouse-sync.yml. This action syncs the repository's CLAUDE.md / PROGRESS.md, tagged as project:<repo-name> (can be overridden with the slug input; base-url points to the self-hosted instance).

Billing/Stripe setup: BaseMouse renders the paid Starter, Team, and Enterprise plans from /api/billing/config. POST /api/checkout creates a Stripe Checkout Session for self-service tiers when Stripe is configured. If environment variables are missing, the UI and API degrade to a clear contact-sales state; no payment or customer data is stored locally. You need to create products in Stripe with monthly recurring prices, tag each price with tier metadata (starter or team); create a webhook endpoint pointing to /api/stripe/webhook and copy the signing secret to STRIPE_WEBHOOK_SECRET; set the environment variables and enable CHECKOUT_ENABLED=true. Restricted keys (rk_…) are recommended, with a minimal scope of write access for Checkout Sessions and Billing Portal Sessions, plus read access for Checkout Sessions for the claim verification path.

Seed documents: each document is normalized by src/store.js, given deterministic source metadata, and a stable 16-character SHA-256 checksum is generated from the normalized content.

The hosted service runs on Kubernetes, continuously deployed from main. Self-hosters can use the Docker Compose example in deployment/compose/ to deploy the same image.

If the same site is served on both the apex and www hostnames, you can set CANONICAL_HOST to the bare domain (e.g. example.com), and GET and HEAD requests arriving at www.<CANONICAL_HOST> will be 308 redirected to the bare host, so crawlers index only one source. Only GET and HEAD are redirected; POST traffic (API, MCP, webhook) is unaffected. If not set, the redirect is disabled (default).

Documentation: docs/getting-started.md (first API and MCP endpoint calls), docs/agent-integration.md (connecting BaseMouse to agents and MCP clients), docs/client-libraries.md (JavaScript and Python API clients), docs/retrieval-eval.md (golden-query retrieval quality tooling), docs/demo-corpus-agent-governance.md (public Agent Governance Demo corpus, pages, and evaluation baseline), docs/self-hosted.md (running BaseMouse + local LLM + Slack inside a corporate network).

Use cases

• Workspaces that need to provide shared, versioned, traceable memory for AI agents.
• Scenarios where agents need to cite sources, checksums, and document versions.
• Teams that need local-first/self-hosted privacy, append-only history, and audit trails.
• Developers who need to sync coding workspaces (CLAUDE.md / PROGRESS.md) to a knowledge base and make them available to agents via MCP.

Limitations

• The current vector retrieval is local offline hashed-feature embedding, a shared vocabulary overlap in a dense space, not a learned semantic model.
• Graph expansion in hybrid retrieval is only one hop, not full GraphRAG.
• Roadmap (not yet implemented, direction only): real-corpus retrieval evaluation suite, semantic vector retrieval, full GraphRAG, memory capsules, built-in agent sandbox, precise canvas UX, MeshAI integration (OpenTelemetry).
• MeshAI integration is disabled by default and is a no-op until configured; it only sends retrieval evidence (query, countof documents, document id), not document bodies.
• Paid plans exist, but specific pricing and feature details are not yet provided.
• Hosted service status is live (paid plans), version v0.3.