Builderforce Memory

@seanhogg/builderforce-memory-mcp

Expose @seanhogg/builderforce-memory to any MCP client. One token-saving tool core over a pluggable MemoryBackend, three transports:

Technical report & peer review. This transport is reviewed in the Evermind technical report's adversarial PEER-REVIEW.md. Note before exposing the HTTP handler publicly: the authToken check is a non-constant-time string compare (timing channel) and the handler shares one backend with no per-tenant isolation — a single token reads every tenant's facts. Despite the "multi-tenant" note above, real isolation (token→namespace mapping, constant-time compare, rate limiting) is not yet implemented. Tracked as EVM-3 in the Builderforce.ai Consolidated Gap Register. Resolved in v2026.6.34: the HTTP handler now uses a constant-time token compare and per-tenant namespace isolation (see the resolution addendum in PEER-REVIEW.md).

Why this saves tokens

The point of an external memory store is fetch-on-demand instead of pinning your whole memory file into every prompt. That only pays off if recall is selective, so the caps are enforced server-side in tools.ts:

• memory_recall returns a ranked top-K (default 5, hard-capped), never the store.
• Each entry's content is truncated (default 500 chars) before it hits context.
• There is no "return everything" tool — a dump-all is more expensive than inlining.
• memory_compact shrinks a fact the local Evermind has already ABSORBED down to a one-line pointer stub, so it stops filling context. It is lossless: a recall probe must pass first, and the original is archived (recall still returns it) — see below. It writes through the live store, which keeps memory and the on-disk snapshot in agreement.
• Recall ranks by hybrid fusion (BM25 ⊕ optional CPU SSM embedding, RRF, MMR) and then weights by importance (×(0.5+importance)) and a 90-day half-life recency decay — createLocalMemoryStoreBackend({ ranking: false }) turns the signals off.

Tool descriptions are prescriptive ("call this before answering when…") because recent Claude models reach for tools more conservatively; the trigger condition in the description is what drives should-call rate. Pair this with prompt caching (keep the tool set identical across tenants so the cached prefix survives) and context editing (prune stale recalled facts) for the full win.

The seam

Everything is written against MemoryBackend:

interface MemoryBackend {  recall(query: string, topK: number): Promise<RecallHit[]>;  // semantic  get(key: string): Promise<RecallHit | undefined>;           // exact  recallByTag(tag: string, limit: number): Promise<RecallHit[]>;  remember?(input: RememberInput): Promise<void>;             // optional → read-only backends omit  forget?(key: string): Promise<void>;}

Ship the local MemoryStoreBackend (IndexedDB via @seanhogg/builderforce-memory) today; drop in a networked builderforce.ai adapter later with zero changes to tools or transports.

Quick start — in-process with the Claude Agent SDK

import { query } from "@anthropic-ai/claude-agent-sdk";import { createMemoryMcpServer, createLocalMemoryStoreBackend } from "@seanhogg/builderforce-memory-mcp";
const backend = await createLocalMemoryStoreBackend();          // IndexedDB (fake-indexeddb in Node)const memory  = await createMemoryMcpServer(backend);           // type:"sdk" config
for await (const msg of query({  prompt: "What language does this user prefer? Check memory first.",  options: {    mcpServers: { builderforce_memory: memory },    allowedTools: ["mcp__builderforce_memory__*"],             // auto-approve, no prompts  },})) {  if (msg.type === "result" && msg.subtype === "success") console.log(msg.result);}

The snapshot is shared — the server watches it

With persistFile set, the store lives in memory and the JSON snapshot is the source of truth across process lifetimes. Other processes edit that file too (the BuilderForce VS Code extension rewrites absorbed entries to stubs in place), so before every operation the backend stats the file and re-hydrates from disk when it changed underneath — otherwise this server, still holding the pre-edit bodies, would re-snapshot over that work on its next write. Its own writes are stamped (mtime + size + content hash) the moment they land, so the steady-state cost is one stat and there is no write-loop.

SSM-embedding recall — including on a headless host (no GPU)

With no model configured the local backend ranks recall lexically (BM25). Point it at an Evermind checkpoint and the ordering becomes the SSM embedding's cosine ranking fused with the lexical one (Reciprocal Rank Fusion — dense ⊕ sparse, so exact tokens like identifiers and error codes are still caught). Every memory_recall result names the ranker it used, so a degrade to lexical is never silent:

Ranked by: semantic recall (SSM embedding fused with lexical).Ranked by: lexical recall (fallback - no embedding model loaded).

The stdio/HTTP servers do not need a GPU for this. EvermindLM is a pure-CPU model and EvermindLM.embed() mean-pools + L2-normalises the same hidden state the GPU HybridMambaModel.embed() does, to the same contract. Configure it with:

Vectors are cached across process lifetimes (stamped with the model's fingerprint, so an adapted checkpoint invalidates them), because a per-session subprocess that re-embedded the whole store on its first recall would cost more than the lexical ranking it replaces.

In-process hosts pass an embedder directly — reuse an already-loaded GPU Evermind runtime rather than standing up a second model:

const backend = await createLocalMemoryStoreBackend({ runtime: ssmMemoryService.runtime });

Either way, recall quality improves automatically as that model is adapted/distilled.

Experience — what Evermind has done (opt-in)

Facts are one kind of learned item; experience is another. An episode is a recorded demonstration (a program and the UI steps a person took in it), a skill is what Train Once compiles from one (typed values become parameters, secrets never stored, irreversible clicks gated for approval), and a run is one execution with its audit trail. The domain lives in @seanhogg/builderforce-memory-engine; this server keeps it durable and exposes it.

Set BUILDERFORCE_MEMORY_EXPERIENCE=1 to register the tools (Synapse does). Off by default, so ordinary coding-agent installs never carry them in their tool list.

Stored beside the memory snapshot as experience.json (shared across processes exactly like memory.json) plus episodes/. Never served to a token-selected tenant of the HTTP handler.

One-shot install into any MCP host (not just Claude)

# Auto-detect installed agents and register the memory server into each:npx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install
npx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install --host=allnpx -y -p @seanhogg/builderforce-memory-mcp builderforce-memory-install --host=cursor,windsurf

Writes the stdio server entry into each host's own config, idempotently and with .bak backups. Supported hosts: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Cline, Gemini CLI, Codex CLI. Every agent points at one shared store (resolveMemoryFile(): ~/.builderforce-memory/memory.json, or the legacy ~/.claude/builderforce-memory/memory.json when that is where the live store is; override with --memory-file / BUILDERFORCE_MEMORY_FILE; the hook script resolves the same way), so a fact remembered in one agent is recalled in another. --readonly drops the write tools; --local=<dist/bin/stdio.js> runs a checkout for development.

The same launch spec is exported for programmatic use: buildServerSpec() / installMemoryServer() (see src/install/).

Claude Code: the self-driving "memory combo"

Registering the server gives Claude Code the memory tools. For Claude Code the installer ALSO wires hooks so memory is self-driving instead of advisory (skip with --no-hooks):

All four point at one generated, dependency-free hook script (~/.claude/builderforce-memory/bfmem-hook.mjs, four modes) plus a companion skill. Idempotent + .bak-safe. Source of truth: src/install/claude-hooks.ts (installClaudeCombo / bfmemHookSource).

Quick start — stdio (any process / language)

npx -y @seanhogg/builderforce-memory-mcp        # serves the local MemoryStore over stdio

mcpServers: {  builderforce_memory: { type: "stdio", command: "npx", args: ["-y", "@seanhogg/builderforce-memory-mcp"] },}

Env: BUILDERFORCE_MEMORY_DB (db name), BUILDERFORCE_MEMORY_READONLY=1 (drop write tools).

Quick start — HTTP (multi-tenant)

BUILDERFORCE_MEMORY_TOKEN=secret PORT=8787 npx @seanhogg/builderforce-memory-mcp-http

mcpServers: {  builderforce_memory: {    type: "http",    url: "http://localhost:8787",    headers: { Authorization: "Bearer secret" },  },}

Or mount createMemoryHttpHandler(backend, { authToken }) on your own Node/Express server against any backend (including a future remote one).

Custom / remote backend

Implement MemoryBackend and hand it to any transport:

import { createMemoryMcpServer, type MemoryBackend } from "@seanhogg/builderforce-memory-mcp";
const remote: MemoryBackend = {  recall:      (q, k)   => bfClient.search(q, k),  get:         (key)    => bfClient.get(key),  recallByTag: (t, lim) => bfClient.byTag(t, lim),  remember:    (input)  => bfClient.put(input),  forget:      (key)    => bfClient.delete(key),};const server = await createMemoryMcpServer(remote);

Compaction rules (@seanhogg/builderforce-memory-mcp/compaction)

The stub format that memory_compact writes ([absorbed→Evermind vN] <first line>) is published as a dependency-free subpath. An external compactor imports its rules from it, so its stubs are byte-identical to the server's and neither re-stubs the other.

Lossless contract (what every compactor must do, in order):

1. planLosslessCompaction(candidates, { probe, version }) — the structural rules (planCompaction: skip stubs, never grow an entry) plus a recall probe: probeQuestionFor(key, content) blanks the fact's most identifying token and the local Evermind must supply it (probePasses). No probe, or a wrong answer, leaves the fact uncompacted (no_probe / probe_failed).
2. Archive every write's archive row (mergeArchive into defaultArchiveFile(memoryFile) → memory.archive.json) — durably, before any stub is written. The archive sits outside the snapshot, is only merged into and never pruned, so it survives snapshot rewrites, forget, and the 10,000-entry cap.
3. Write the stubs.

Reads resolve a stub to its archived original (RecallHit.content = full text, RecallHit.stub = the stored stub). A stub with no archive is contentLost: tools and the Claude Code hooks label it CONTENT_LOST_LABEL — "(content lost — re-verify before relying on it)" — and the hooks importance-demote it. memory_restore (file on the stdio bin, inline json everywhere) brings the text back from [{key, content}] or the Evermind coordinator's [{id, text}] mem: dump: matched by key (an id loses its mem: prefix), else uniquely by first line against the stub's pointer; the text is archived beside the stub, so the token saving stays.

Every overwrite of a shared store file (SharedJsonFile: the snapshot, the archive, experience.json) first rotates the previous version into <file>.bak.1 … .bak.3.

Dependencies

@modelcontextprotocol/sdk + zod are hard deps. @anthropic-ai/claude-agent-sdk (SDK transport), @seanhogg/builderforce-memory + fake-indexeddb (local backend) are optional peers, imported indirectly — install only what your transport/backend needs.