cmd-mod-supermemory

A Command Code mod that gives your agent persistent memory, backed by Supermemory — project knowledge that survives sessions, plus personal preferences scoped to the repository you are in.

Tested against Command Code CLI 1.62.0 (desktop app 0.1.37) / @commandcode/harness 0.1.0. The ModApi is documented as experimental — pin the version you ship against.

What it does

• Project memory — architecture, conventions, setup steps, accepted decisions (scope: "project")
• Personal memory — your preferences for this repo (scope: "user")
• Automatic capture — saves the conversation at run end (onRunEnd)
• Automatic recall — injects a first-message context block plus a per-turn recall directive
• Repo-scoped — memories are keyed by a container tag derived from the git remote (repo_<name>__<hash>), so two clones of the same repo share memory and unrelated projects never collide. Outside a git repo the absolute path is used instead.

Without an API key the mod still loads, notifies you once, and does nothing else:

supermemory: no API key — set SUPERMEMORY_API_KEY or --mod-option api-key=sm_...

Install

cmdc mods add sstreichan/cmd-mod-supermemory --global

--global installs for all projects (user scope). Without it the mod is installed project-scoped to the current directory.

Or instruct an agent with this prompt:

Read the README.md of the Command Code mod supermemory (https://github.com/sstreichan/cmd-mod-supermemory) and perform the installation described there. Verify afterwards with `cmdc mods list` that `supermemory` is listed.

Verify the install

cmdc mods list

supermemory must appear under Package sources with no warning:

Mods (1)
  supermemory · user · ~/.commandcode/mods/.registry/git/github.com/sstreichan/cmd-mod-supermemory/supermemory.ts

Package sources (1)
  git:github.com/sstreichan/cmd-mod-supermemory · installed

Then start a session and ask the agent to store something:

Remember that this repo uses pnpm, not npm.

The agent calls the supermemory tool with mode: "add" and reports a memory id. Confirm it landed:

/memory list

A returned memory means the mod loaded, reached the API and authenticated. /memory help lists the available commands; cmdc mods list only proves registration, not that the API key works.

Existing local install

A hand-copied ~/.commandcode/mods/supermemory.ts shadows the git install — both register the mod name supermemory, and cmdc mods list reports the collision:

git:github.com/sstreichan/cmd-mod-supermemory · installed, but provides no mods
⚠ duplicate mod name "supermemory" — first one wins

The copy keeps loading, so the mod appears to work while never receiving updates. Delete the loose file once the git source is registered:

rm ~/.commandcode/mods/supermemory.ts

cmdc mods list must then show supermemory under Package sources with no warning. From here on, cmdc mods update pulls new releases.

Configure

Set the API key in one of these — first match wins:

1. --mod-option api-key=sm_...
2. apiKey in ~/.commandcode/supermemory.jsonc
3. the SUPERMEMORY_API_KEY environment variable

The base URL follows the same order (base-url, baseUrl, then SUPERMEMORY_API_URL / SUPERMEMORY_BASE_URL), defaulting to https://api.supermemory.ai.

Everything else lives in ~/.commandcode/supermemory.jsonc — see supermemory.jsonc.example for the full list with defaults:

Key	Default	Meaning
similarityThreshold	0.55	Minimum similarity for retrieval
maxMemories	5	Memories injected per request
maxProjectMemories	10	Project memories in the first-message context
maxProfileItems	5	Profile facts injected per section
injectProfile	true	Include the Supermemory user profile
autoIngest	true	Save the conversation at run end
autoRecall	true	Append the recall directive each turn
captureEveryNTurns	3	Save every N messages (0 = one batch at session end)
compactionThreshold	0.8	Context ratio that triggers the compaction injection
contextLimit	200000	Your model's context window in tokens — the denominator for that ratio
keywordPatterns	[]	Extra regexes that trigger the "remember this" nudge (added to the defaults)
projectContainerTag / userContainerTag	–	Extra container tags to read on top of the derived one

The numeric and boolean keys are also settable per launch as flags, e.g. cmdc --mod-option api-key=sm_... --mod-option max-memories=8. supermemory.jsonc may contain // and /* */ comments.

contextLimit has to be set by hand. The ModApi exposes no model-window accessor, and the mod deliberately does not import one from @commandcode/harness: a drop-in mod cannot resolve that package at runtime, so such an import would break loading entirely. Set it to the window of the model you run, or the compaction gate measures the wrong fraction of it.

Usage

The model can call the supermemory tool directly, or you can drive it:

Command	Does
/memory add <text>	Store a memory
/memory search <query>	Search memories
/memory profile [query]	Show the user profile
/memory list [scope]	List recent memories
/memory forget <id>	Delete a memory
/memory help	Usage guide
/supermemory-index	Explore the codebase and store architecture as project memory

Tool modes: add, search, profile, list, forget, help. scope is project (default) or user. Types: project-config, architecture, error-solution, preference, learned-pattern, conversation.

Privacy

• Wrapping text in <private>…</private> redacts it before it is sent to the API.
• Content that is only private is never stored — add rejects it and automatic capture skips it.
• Automatic capture truncates each message to 2000 characters and one batch to 100,000 characters.

Automatic capture is on by default. Turn it off with "autoIngest": false if you would rather decide per memory.

How it works

Hook	Does
transformInput	Detects "remember this"-style keywords in typed prompts (outside code blocks) and prepends a nudge telling the model to store the memory
appendSystemPrompt	Injects the profile, project knowledge and relevant memories once per session, then the recall directive every turn
onRunEnd	Batches the conversation and stores it as a conversation memory
onTurnEnd	Near context capacity, injects a project-facts reminder so compaction keeps them

The appendSystemPrompt output is deliberately kept byte-stable per session — the context is fetched once via a closure flag and the directive is a constant, because the provider's prompt-prefix cache keys off the system prompt bytes. Do not turn the one-time fetch into a per-round fetch.

Development

npm install
npm run typecheck        # tsc --noEmit

Try it without installing:

cp ~/.commandcode/supermemory.jsonc.example ~/.commandcode/  # optional
cmdc --mod ./supermemory.ts

Then /reload after editing — mods load once per process. Verify registration with cmdc mods list; it must list supermemory with no load warning.

If you also have the git source registered, the local --mod copy is redundant — pick one, or the duplicate-name warning above applies.

About types/commandcode-harness.d.ts

The harness is bundled inside the Command Code app and ships no .d.ts files, so this repo carries a small hand-written type surface for the ModApi members the mod uses, wired up through compilerOptions.paths. It is a convenience for tsc and your editor — the mods documentation is the source of truth. It is intentionally permissive: when something needs to be loosened, loosen the shim, not the mod.

License

MIT