Provides persistent, token-saving memory for AI agents by enabling selective recall of durable facts instead of re-reading entire files.
Also known as SeanHogg/builderforce-memory, builderforce-memory, @seanhogg/builderforce-memory-mcp
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 2026.10.82
- Last commit
- Nov 15, 2026
- License
- —
What is Builderforce Memory MCP?
Builderforce Memory provides persistent, token-saving memory for AI agents by enabling selective recall of durable facts instead of re-reading entire files.
Summary generated from the project's README
About Builderforce Memory MCP server
Builderforce Memory provides a persistent storage layer for AI agents to manage durable facts without bloating context windows. Instead of reading entire files, agents use selective recall to fetch only relevant information on demand. This server supports three distinct transport methods: in-process integration for the Claude Agent SDK, stdio for separate processes or different programming languages, and HTTP for networked or multi-tenant environments.
Developers can use the memory_recall tool to retrieve a ranked top-K list of facts, while memory_compact helps manage context by shrinking absorbed facts into one-line pointers. The system uses hybrid fusion ranking, combining lexical BM25 with optional SSM embedding for semantic search. It is designed to work across different AI clients like Claude Desktop, Cursor, and Windsurf, ensuring that a fact remembered in one agent can be recalled by another through a shared memory file.
What you can do with it
- 1Reduce token consumptionAn AI agent can fetch specific facts on demand rather than pinning a massive memory file into every prompt.
- 2Automate memory managementThe system can automatically capture durable instructions or corrections from a user during a session.
- 3Optimize context with compactingYou can shrink facts that the agent has already processed into small stubs to save space.
Written from the project's README. Every use case is checked against a quote from it.
How to install Builderforce Memory MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Builderforce Memory MCP in Claude Code
$ claude mcp add --env 'BUILDERFORCE_API_KEY=<YOUR_BUILDERFORCE_API_KEY>' builderforce-memory -- npx -y @seanhogg/builderforce-memory-mcpInstall Builderforce Memory MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"builderforce-memory": {
"command": "npx",
"args": [
"-y",
"@seanhogg/builderforce-memory-mcp"
],
"env": {
"BUILDERFORCE_API_KEY": "<YOUR_BUILDERFORCE_API_KEY>"
}
}
}
}Install Builderforce Memory MCP in VS Code
.vscode/mcp.json
{
"servers": {
"builderforce-memory": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@seanhogg/builderforce-memory-mcp"
],
"env": {
"BUILDERFORCE_API_KEY": "<YOUR_BUILDERFORCE_API_KEY>"
}
}
}
}Install Builderforce Memory MCP in VS Code CLI
$ code --add-mcp '{"name":"builderforce-memory","type":"stdio","command":"npx","args":["-y","@seanhogg/builderforce-memory-mcp"],"env":{"BUILDERFORCE_API_KEY":"<YOUR_BUILDERFORCE_API_KEY>"}}'Install Builderforce Memory MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"builderforce-memory": {
"command": "npx",
"args": [
"-y",
"@seanhogg/builderforce-memory-mcp"
],
"env": {
"BUILDERFORCE_API_KEY": "<YOUR_BUILDERFORCE_API_KEY>"
}
}
}
}Install Builderforce Memory MCP in Codex
$ codex mcp add builderforce-memory --env 'BUILDERFORCE_API_KEY=<YOUR_BUILDERFORCE_API_KEY>' -- npx -y @seanhogg/builderforce-memory-mcpInstall Builderforce Memory MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.builderforce-memory] command = "npx" args = ["-y", "@seanhogg/builderforce-memory-mcp"] [mcp_servers.builderforce-memory.env] BUILDERFORCE_API_KEY = "<YOUR_BUILDERFORCE_API_KEY>"
Install Builderforce Memory MCP in Gemini CLI
$ gemini mcp add -s user -e 'BUILDERFORCE_API_KEY=<YOUR_BUILDERFORCE_API_KEY>' builderforce-memory npx -- -y @seanhogg/builderforce-memory-mcpInstall Builderforce Memory MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"builderforce-memory": {
"command": "npx",
"args": [
"-y",
"@seanhogg/builderforce-memory-mcp"
],
"env": {
"BUILDERFORCE_API_KEY": "<YOUR_BUILDERFORCE_API_KEY>"
}
}
}
}Configuration
BUILDERFORCE_API_KEYSecretBuilderforce tenant API key (bfk_*). When set, additionally exposes the token_usage and model_efficiency cost tools.
BUILDERFORCE_MEMORY_FILEAbsolute path to the JSON snapshot that makes memory survive restarts. Defaults to ~/.builderforce-memory/memory.json, which every MCP host on the machine shares.
BUILDERFORCE_MEMORY_READONLYSet to 1 to expose recall only (disables memory_remember and memory_forget).
BUILDERFORCE_MEMORY_TOKEN
| Name | Description | |
|---|---|---|
| BUILDERFORCE_API_KEY | Builderforce tenant API key (bfk_*). When set, additionally exposes the token_usage and model_efficiency cost tools. | Secret |
| BUILDERFORCE_MEMORY_FILE | Absolute path to the JSON snapshot that makes memory survive restarts. Defaults to ~/.builderforce-memory/memory.json, which every MCP host on the machine shares. | |
| BUILDERFORCE_MEMORY_READONLY | Set to 1 to expose recall only (disables memory_remember and memory_forget). | |
| BUILDERFORCE_MEMORY_TOKEN | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachableseanhogg/builderforce-memory is public and reachablegithub.com/seanhogg/builderforce-memory ↗Pass
- Package names this repository as its source@seanhogg/builderforce-memory-mcp names seanhogg/builderforce-memory as sourcenpmjs.com/package/@seanhogg/builderforce-memory-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @seanhogg/builderforce-memory-mcpnpmjs.com/package/@seanhogg/builderforce-memory-mcp/v/2026.1 ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-13github.com/seanhogg/builderforce-memory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @seanhogg/builderforce-memory-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@seanhogg/builderforce-memory-mcp
Expose @seanhogg/builderforce-memory to any MCP client. One token-saving
tool core over a pluggable MemoryBackend, three transports:
| Transport | Factory | Consumed as | Use when |
|---|---|---|---|
| In-process (Claude Agent SDK) | createMemoryMcpServer(backend) |
the returned type:"sdk" object |
the consuming product is TS and runs @anthropic-ai/claude-agent-sdk in-process — lowest latency |
| stdio | runStdio(backend) / npx @seanhogg/builderforce-memory-mcp |
{ type:"stdio", command, args } |
any language / separate process; decouples the SSM+IndexedDB deps from the consumer |
| HTTP (Streamable) | createMemoryHttpHandler(backend, { authToken }) |
{ type:"http", url, headers } |
multi-tenant / networked (builderforce.ai hosting, remote agents) |
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: theauthTokencheck is a non-constant-time string compare (timing channel) and the handler shares onebackendwith 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 asEVM-3in 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 inPEER-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_recallreturns 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_compactshrinks 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:
| Env | Meaning |
|---|---|
BUILDERFORCE_MEMORY_MODEL |
Path to a .evermind package holding an evermind-lm. |
BUILDERFORCE_MEMORY_TOKENIZER |
Tokenizer JSON for that checkpoint. Default <model>.tokenizer.json. |
BUILDERFORCE_MEMORY_VECTORS |
Vector-cache path. Defaults beside the memory snapshot. |
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.
| Tools | |
|---|---|
experience_info |
Snapshot file, screenshot folder, model path, counts. |
experience_forget_all |
Delete every episode, screenshot, skill and run (confirm: true). Memories and the model are untouched. |
episode_save / _list / _get / _forget |
Demonstrations. Screenshots go in episodes/<id>/ and are deleted with the episode. |
skill_preview / _compile / _list / _get / _forget / _schedule, skills_due |
Train Once and routines. |
run_start / _step / _finish / _list / _get |
Runs and their audit trail (newest 500 kept). |
experience_train |
Adapt the private model (BUILDERFORCE_MEMORY_MODEL) on every procedure it has not learned, through the engine's one adaptation recipe. The previous model is kept as <model>.prev. Opt-in curate: true first leaves out procedures whose runs mostly fail and near-copies (of each other, or of the 200 most recently learned), listing each one dropped; it is reconsidered next time. |
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=all
npx -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):
| Hook | Behaviour |
|---|---|
SessionStart |
Inject a digest of the top durable memories. |
PreCompact |
Flush durable learnings before the window is summarised. |
UserPromptSubmit |
Contextual recall — score memories against the prompt and inject the relevant ones, so a stored fact is retrieved at the decision point, not only at session start. |
Stop |
Autonomous capture — if the user's last message was a durable instruction/correction and it wasn't consolidated this turn, BLOCK the stop with a directive to memory_remember. Capture flows through the MCP write path (never racing the snapshot); a stop_hook_active guard means at most one nudge per turn. |
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):
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).- Archive every write's
archiverow (mergeArchiveintodefaultArchiveFile(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. - 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.
Builderforce Memory MCP questions
How do I add Builderforce Memory MCP to Claude Code?
Run claude mcp add --env 'BUILDERFORCE_API_KEY=<YOUR_BUILDERFORCE_API_KEY>' builderforce-memory -- npx -y @seanhogg/builderforce-memory-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Builderforce Memory MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does this server save tokens?
It uses fetch-on-demand recall instead of pinning entire memory files into every prompt, returning only ranked top-K results with truncated content.
Can I use this without a GPU?
Yes, the stdio and HTTP servers do not require a GPU; they can use a pure-CPU model for semantic ranking.
How is memory recall ranked?
Recall uses hybrid fusion, combining BM25 lexical ranking with optional SSM embedding cosine ranking.