From a0003e82d6d638f88f85db7f79509187f63ebe4a Mon Sep 17 00:00:00 2001
From: Tomas <180413002+Tomauskasz@users.noreply.github.com>
Date: Wed, 2 Sep 2026 08:20:41 +0300
Subject: [PATCH 1/9] feat(recall): mirror Codex recall settings
Context:
Allow Claude's SessionStart and prompt hooks to consume shared Codex recall settings and apply them across the repository and configured custom containers.
Changes:
- Load optional shared settings before Claude-specific overrides and expose memory counts, context budgets, and automatic-container configuration.
- Fan out profile requests, tolerate partial container failures, globally rank and deduplicate prompt matches, and merge profile facts.
- Bound complete prompt and SessionStart contexts, retain prompt filtering and session deduplication, and mark only emitted memories as recalled.
- Document the configuration precedence and add multi-container, budget, partial-failure, and profile-merge coverage.
Impact:
Claude can use the same maxMemories, maxProfileItems, maxRecallTokens, maxPromptRecallTokens, autoRecallContainers, and customContainers values as Codex. Existing defaults remain five memories, five profile items per section, a 2,500-token context budget, and disabled automatic custom-container recall.
Validation:
- npm test: 27 tests passed.
- Node syntax checks passed for all changed hook modules.
- git diff --staged --check passed.
- npm run lint exited successfully; the repository Biome configuration processed only biome.json and reported a schema-version information message.
Notes:
Prompt recall still uses /v4/profile. Open PR #114 independently proposes /v3/search and may require conflict resolution before merge.
Signed-off-by: Tomas <180413002+Tomauskasz@users.noreply.github.com>
---
README.md | 35 +++--
plugin/hooks/lib/api.js | 17 ++-
plugin/hooks/lib/context.js | 211 +++++++++++++++++++++++++++++++
plugin/hooks/lib/settings.js | 40 +++++-
plugin/hooks/recall-directive.js | 85 ++++++-------
plugin/hooks/session-start.js | 65 +++++-----
test/unit.mjs | 147 +++++++++++++++++++++
7 files changed, 501 insertions(+), 99 deletions(-)
create mode 100644 plugin/hooks/lib/context.js
diff --git a/README.md b/README.md
index 6de17cc..59aa69a 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ export SUPERMEMORY_CC_API_KEY="sm_..."
## How It Works
-- **Reasoned recall** — Before each turn, Claude decides whether recalling memory would actually help your current message, and only searches when it's worth it — every turn, once in a while, or not at all. The search runs automatically (no permission prompt), just like auto-capture. Searching only when needed also keeps more usage on your plan
+- **Automatic recall** — Every substantive prompt searches the repository and configured recall containers, then injects globally ranked, deduplicated matches within the configured context budget
- **supermemory-search** — Ask about past work or previous sessions, Claude searches your memories
- **supermemory-save** — Ask to save something important, Claude saves it for the team
@@ -85,9 +85,19 @@ SUPERMEMORY_DEBUG=true # Optional: enable debug logging
**Global Settings** — `~/.supermemory-claude/settings.json`
+Claude first loads shared recall settings from `~/.codex/supermemory.json` when
+that file exists. Claude-specific settings override the shared values.
+
```json
{
- "maxProfileItems": 5,
+ "maxMemories": 15,
+ "maxProfileItems": 15,
+ "maxRecallTokens": 5000,
+ "maxPromptRecallTokens": 2000,
+ "autoRecallContainers": true,
+ "customContainers": [
+ { "tag": "coding_personal", "description": "Cross-project coding preferences." }
+ ],
"signalExtraction": true,
"signalKeywords": ["remember", "architecture", "decision", "bug", "fix"],
"signalTurnsBefore": 3,
@@ -95,14 +105,19 @@ SUPERMEMORY_DEBUG=true # Optional: enable debug logging
}
```
-| Option | Description |
-| ------------------- | --------------------------------------------- |
-| `maxProfileItems` | Max memories in context (default: 5) |
-| `recallDirective` | Override the built-in reasoned-recall instruction Claude is given |
-| `signalExtraction` | Only capture important turns (default: false) |
-| `signalKeywords` | Keywords that trigger capture |
-| `signalTurnsBefore` | Context turns before signal (default: 3) |
-| `includeTools` | Tools to explicitly capture |
+| Option | Description |
+| ------------------------- | ----------- |
+| `maxMemories` | Maximum globally ranked prompt matches across all searched containers (default: 5) |
+| `maxProfileItems` | Maximum static and dynamic profile items per section (default: 5) |
+| `maxRecallTokens` | Approximate whole-context SessionStart budget (default: 2500) |
+| `maxPromptRecallTokens` | Approximate whole-context prompt-recall budget; defaults to `maxRecallTokens` |
+| `autoRecallContainers` | Search every valid `customContainers` entry automatically (default: false) |
+| `customContainers` | Additional recall containers with `tag` and `description` fields |
+| `recallDirective` | Replace automatic prompt recall with a custom advisory instruction |
+| `signalExtraction` | Only capture important turns (default: false) |
+| `signalKeywords` | Keywords that trigger capture |
+| `signalTurnsBefore` | Context turns before signal (default: 3) |
+| `includeTools` | Tools to explicitly capture |
**Project Config** — `.claude/.supermemory-claude/config.json`
diff --git a/plugin/hooks/lib/api.js b/plugin/hooks/lib/api.js
index b5c3e0d..0c5b606 100644
--- a/plugin/hooks/lib/api.js
+++ b/plugin/hooks/lib/api.js
@@ -51,6 +51,21 @@ function getProfile(baseUrl, apiKey, containerTag, query, options = {}) {
return post(baseUrl, apiKey, '/v4/profile', { containerTag, q: query }, options.timeoutMs);
}
+async function getProfiles(baseUrl, apiKey, containerTags, query, options = {}) {
+ const settled = await Promise.allSettled(
+ [...new Set(containerTags.filter(Boolean))].map((containerTag) =>
+ getProfile(baseUrl, apiKey, containerTag, query, options),
+ ),
+ );
+ const profiles = settled
+ .filter((result) => result.status === 'fulfilled')
+ .map((result) => result.value);
+ if (profiles.length === 0) {
+ throw settled.find((result) => result.status === 'rejected')?.reason;
+ }
+ return profiles;
+}
+
function addMemory(baseUrl, apiKey, content, containerTag, metadata, options = {}) {
const body = {
content,
@@ -62,4 +77,4 @@ function addMemory(baseUrl, apiKey, content, containerTag, metadata, options = {
return post(baseUrl, apiKey, '/v3/documents', body, options.timeoutMs);
}
-module.exports = { AGENT_ENTITY_CONTEXT, getProfile, addMemory };
+module.exports = { AGENT_ENTITY_CONTEXT, getProfile, getProfiles, addMemory };
diff --git a/plugin/hooks/lib/context.js b/plugin/hooks/lib/context.js
new file mode 100644
index 0000000..571742c
--- /dev/null
+++ b/plugin/hooks/lib/context.js
@@ -0,0 +1,211 @@
+const RECALL_MIN_SIMILARITY = 0.55;
+const CHARS_PER_TOKEN = 4;
+
+function singleLine(value) {
+ return String(value || '')
+ .replace(/\s+/g, ' ')
+ .trim();
+}
+
+function resultText(result) {
+ return [
+ result?.memory,
+ result?.chunk,
+ result?.content,
+ result?.text,
+ result?.context,
+ ].find((value) => typeof value === 'string' && value.trim())?.trim() || '';
+}
+
+function stringValue(...values) {
+ return values.find(
+ (value) => typeof value === 'string' && value.trim().length > 0,
+ )?.trim();
+}
+
+function provenance(result) {
+ const metadata =
+ result?.metadata && typeof result.metadata === 'object' ? result.metadata : {};
+ return {
+ title: stringValue(result?.title, metadata.title),
+ filepath: stringValue(
+ result?.filepath,
+ result?.filePath,
+ result?.path,
+ metadata.filepath,
+ metadata.filePath,
+ metadata.path,
+ ),
+ };
+}
+
+function normalize(value) {
+ return String(value || '')
+ .toLowerCase()
+ .trim();
+}
+
+function dedupe(items, keyFor) {
+ const seen = new Set();
+ return items.filter((item) => {
+ const key = normalize(keyFor(item));
+ if (!key || seen.has(key)) return false;
+ seen.add(key);
+ return true;
+ });
+}
+
+function score(result) {
+ if (Number.isFinite(result.similarity)) return result.similarity;
+ if (Number.isFinite(result.score)) return result.score;
+ return -1;
+}
+
+function mergeProfileResults(responses, maxMemories) {
+ const staticFacts = dedupe(
+ responses.flatMap((response) => response?.profile?.static || []),
+ (fact) => fact,
+ );
+ const staticKeys = new Set(staticFacts.map(normalize));
+ const dynamicFacts = dedupe(
+ responses.flatMap((response) => response?.profile?.dynamic || []),
+ (fact) => fact,
+ ).filter((fact) => !staticKeys.has(normalize(fact)));
+
+ const searchResults = dedupe(
+ responses
+ .flatMap((response) => response?.searchResults?.results || [])
+ .filter((result) => resultText(result))
+ .filter((result) => {
+ const relevance = score(result);
+ return relevance < 0 || relevance >= RECALL_MIN_SIMILARITY;
+ })
+ .sort((a, b) => {
+ const relevance = score(b) - score(a);
+ if (relevance !== 0) return relevance;
+ return Date.parse(b.updatedAt || 0) - Date.parse(a.updatedAt || 0);
+ }),
+ (result) => resultText(result) || result.id,
+ )
+ .slice(0, Math.max(0, maxMemories))
+ .map((result) => ({
+ ...result,
+ memory: resultText(result),
+ ...provenance(result),
+ }));
+
+ return {
+ profile: { static: staticFacts, dynamic: dynamicFacts },
+ searchResults: { results: searchResults },
+ };
+}
+
+function getRecallContainerTags(containerTag, config) {
+ return [
+ ...new Set([
+ containerTag,
+ ...(config.autoRecallContainers
+ ? config.customContainers.map((container) => container.tag.trim())
+ : []),
+ ]),
+ ];
+}
+
+function formatBoundedItems(items, maxTokens, limitName, render) {
+ if (!Number.isFinite(maxTokens) || maxTokens <= 0) {
+ throw new RangeError(`${limitName} must be a positive number`);
+ }
+ const maxChars = Math.floor(maxTokens * CHARS_PER_TOKEN);
+ if (render('').length > maxChars) {
+ throw new RangeError(`${limitName} is too small for fixed recall context`);
+ }
+
+ let body = '';
+ const newFacts = [];
+ for (const item of items) {
+ const fullBody = `${body}${item.before}${item.prefix}${item.text}${item.suffix}`;
+ if (render(fullBody).length <= maxChars) {
+ body = fullBody;
+ newFacts.push(item.text);
+ continue;
+ }
+
+ const fixedBody = `${body}${item.before}${item.prefix}${item.suffix}`;
+ const available = maxChars - render(fixedBody).length;
+ if (available > 1) {
+ const emitted = `${item.text.slice(0, available - 1)}…`;
+ body = `${body}${item.before}${item.prefix}${emitted}${item.suffix}`;
+ newFacts.push(emitted);
+ }
+ break;
+ }
+ return { text: newFacts.length > 0 ? render(body) : '', newFacts };
+}
+
+function formatRecallContext(results, options) {
+ const customContainers = options.customContainers || [];
+ const catalog = customContainers.length
+ ? `\n\nConfigured automatic recall containers:\n${customContainers
+ .map(
+ (container) =>
+ `- ${singleLine(container.tag)}: ${singleLine(container.description)}`,
+ )
+ .join('\n')}`
+ : '';
+ const render = (body) => `
+◪ Recalled from supermemory for this prompt (relevance-ranked):
+${body}${catalog}
+
+When one of these shapes your answer, credit it naturally with the ◪ prefix (e.g. "◪ earlier you decided X"); if you name the source, say "from supermemory" — never "from memory". For deeper history, call the supermemory search_memory tool (containerTag: "${options.containerTag}") or launch the context-gatherer agent.
+`;
+ const items = results.slice(0, Math.max(0, options.maxMemories)).map((result, index) => {
+ const memory = singleLine(result.memory);
+ const title = singleLine(result.title);
+ const filepath = singleLine(result.filepath);
+ return {
+ before: index === 0 ? '' : '\n',
+ prefix: `- ◪ ${title && !memory.startsWith(title) ? `${title} — ` : ''}`,
+ text: memory,
+ suffix: filepath ? ` (${filepath})` : '',
+ };
+ });
+ return formatBoundedItems(
+ items,
+ options.maxTokens,
+ 'maxPromptRecallTokens',
+ render,
+ );
+}
+
+function formatSessionContext(result, options) {
+ const take = (facts) =>
+ dedupe(facts, (fact) => fact)
+ .map((fact) => String(fact).trim())
+ .filter(Boolean)
+ .slice(0, Math.max(0, options.maxProfileItems));
+ const facts = [
+ ...take(result?.profile?.static || []),
+ ...take(result?.profile?.dynamic || []),
+ ];
+ const render = (body) => `
+Recalled memory for this project (${options.projectName}). Every line marked ◪ comes from supermemory — when citing one, keep the mark and phrase it naturally. If you name the source, say "from supermemory" — never "from memory".
+This project's memory container: ${options.containerTag}
+
+${body}
+`;
+ const items = facts.map((fact, index) => ({
+ before: index === 0 ? '[Memory Profile]\n' : '\n',
+ prefix: `${index + 1}. ◪ `,
+ text: fact,
+ suffix: '',
+ }));
+ return formatBoundedItems(items, options.maxTokens, 'maxRecallTokens', render);
+}
+
+module.exports = {
+ formatRecallContext,
+ formatSessionContext,
+ getRecallContainerTags,
+ mergeProfileResults,
+ resultText,
+};
diff --git a/plugin/hooks/lib/settings.js b/plugin/hooks/lib/settings.js
index 14907c3..3c6e7df 100644
--- a/plugin/hooks/lib/settings.js
+++ b/plugin/hooks/lib/settings.js
@@ -7,10 +7,20 @@ const { loadProjectConfig } = require('./project-config');
const BASE_URL = 'https://api.supermemory.ai';
const SETTINGS_DIR = path.join(os.homedir(), '.supermemory-claude');
const SETTINGS_FILE = path.join(SETTINGS_DIR, 'settings.json');
+const SHARED_SETTINGS_FILE = path.join(
+ os.homedir(),
+ '.codex',
+ 'supermemory.json',
+);
const DEFAULT_SETTINGS = {
includeTools: [],
+ maxMemories: 5,
maxProfileItems: 5,
+ maxRecallTokens: 2500,
+ maxPromptRecallTokens: null,
+ autoRecallContainers: false,
+ customContainers: [],
debug: false,
injectProfile: true,
recallDirective: null,
@@ -39,13 +49,26 @@ const DEFAULT_SETTINGS = {
function loadSettings() {
const settings = { ...DEFAULT_SETTINGS };
- try {
- if (fs.existsSync(SETTINGS_FILE)) {
- Object.assign(settings, JSON.parse(fs.readFileSync(SETTINGS_FILE, 'utf-8')));
+ for (const file of [SHARED_SETTINGS_FILE, SETTINGS_FILE]) {
+ try {
+ if (fs.existsSync(file)) {
+ Object.assign(settings, JSON.parse(fs.readFileSync(file, 'utf-8')));
+ }
+ } catch (err) {
+ console.error(`Settings: Failed to load ${file}: ${err.message}`);
}
- } catch (err) {
- console.error(`Settings: Failed to load ${SETTINGS_FILE}: ${err.message}`);
}
+ settings.maxPromptRecallTokens ??= settings.maxRecallTokens;
+ settings.customContainers = Array.isArray(settings.customContainers)
+ ? settings.customContainers.filter(
+ (container) =>
+ container &&
+ typeof container.tag === 'string' &&
+ container.tag.trim() &&
+ typeof container.description === 'string' &&
+ container.description.trim(),
+ )
+ : [];
if (process.env.SUPERMEMORY_DEBUG === 'true') settings.debug = true;
return settings;
}
@@ -144,12 +167,19 @@ function getRecallConfig(cwd) {
const projectConfig = loadProjectConfig(cwd || process.cwd());
return {
directive: projectConfig?.recallDirective || settings.recallDirective || null,
+ maxMemories: settings.maxMemories,
+ maxProfileItems: settings.maxProfileItems,
+ maxRecallTokens: settings.maxRecallTokens,
+ maxPromptRecallTokens: settings.maxPromptRecallTokens,
+ autoRecallContainers: settings.autoRecallContainers,
+ customContainers: settings.customContainers,
};
}
module.exports = {
SETTINGS_DIR,
SETTINGS_FILE,
+ SHARED_SETTINGS_FILE,
DEFAULT_SETTINGS,
loadSettings,
getApiKey,
diff --git a/plugin/hooks/recall-directive.js b/plugin/hooks/recall-directive.js
index 89d8cb6..7342e5d 100644
--- a/plugin/hooks/recall-directive.js
+++ b/plugin/hooks/recall-directive.js
@@ -2,9 +2,15 @@ const crypto = require('node:crypto');
const fs = require('node:fs');
const path = require('node:path');
-const { getProfile } = require('./lib/api');
+const { getProfiles } = require('./lib/api');
const { BRAND, gray, red } = require('./lib/colors');
const { getContainerTag } = require('./lib/container-tag');
+const {
+ formatRecallContext,
+ getRecallContainerTags,
+ mergeProfileResults,
+ resultText,
+} = require('./lib/context');
const { getUserFriendlyError } = require('./lib/error-helpers');
const { loadProjectConfig } = require('./lib/project-config');
const {
@@ -28,9 +34,6 @@ const { readStdin, writeOutput } = require('./lib/stdin');
// to spend a tool call. A configured recallDirective restores advisory mode.
const MIN_PROMPT_LENGTH = 12;
const MAX_QUERY_LENGTH = 500;
-const MAX_RESULTS = 5;
-const MAX_RESULT_CHARS = 300;
-const MIN_SIMILARITY = 0.55;
const SEARCH_TIMEOUT_MS = 4000;
const MAX_SEEN_HASHES = 500;
@@ -39,16 +42,6 @@ function shouldSkip(prompt) {
return ['/', '!', '#'].includes(prompt[0]);
}
-// Search hits are memory-shaped (.memory) or document/chunk-shaped
-// (.chunk/.content/.text, usually with a filepath) — read whichever carries
-// the text.
-function resultText(r) {
- const text = [r?.memory, r?.chunk, r?.content, r?.text].find(
- (v) => typeof v === 'string' && v.trim(),
- );
- return text || null;
-}
-
// A memory injected once this session stays in the conversation, so
// re-injecting it wastes context and makes the banner repeat the same
// number every turn. The seen set lives next to the statusline state and
@@ -74,21 +67,6 @@ function readSeenHashes(sessionDir) {
}
}
-function formatRecall(results, containerTag) {
- const lines = results.map((r) => {
- const text = resultText(r).replace(/\s+/g, ' ').slice(0, MAX_RESULT_CHARS);
- const title = typeof r.title === 'string' && r.title.trim() ? r.title.trim() : null;
- const prefix = title && !text.startsWith(title) ? `${title} — ` : '';
- return `- ◪ ${prefix}${text}${typeof r.filepath === 'string' && r.filepath ? ` (${r.filepath})` : ''}`;
- });
- return `
-◪ Recalled from supermemory for this prompt (relevance-ranked):
-${lines.join('\n')}
-
-When one of these shapes your answer, credit it naturally with the ◪ prefix (e.g. "◪ earlier you decided X"); if you name the source, say "from supermemory" — never "from memory". For deeper history, call the supermemory search_memory tool (containerTag: "${containerTag}") or launch the context-gatherer agent.
-`;
-}
-
async function main() {
const settings = loadSettings();
@@ -96,13 +74,13 @@ async function main() {
const input = await readStdin();
const cwd = input.cwd || process.cwd();
const prompt = (input.prompt || '').trim();
- const { directive } = getRecallConfig(cwd);
+ const recallConfig = getRecallConfig(cwd);
- if (directive) {
+ if (recallConfig.directive) {
writeOutput({
hookSpecificOutput: {
hookEventName: 'UserPromptSubmit',
- additionalContext: directive,
+ additionalContext: recallConfig.directive,
},
});
return;
@@ -123,62 +101,73 @@ async function main() {
}
const containerTag = getContainerTag(cwd);
- const response = await getProfile(
+ const containerTags = getRecallContainerTags(containerTag, recallConfig);
+ const responses = await getProfiles(
getBaseUrl(cwd, projectConfig),
apiKey,
- containerTag,
+ containerTags,
prompt.slice(0, MAX_QUERY_LENGTH),
{ timeoutMs: SEARCH_TIMEOUT_MS },
);
-
- const results = (response?.searchResults?.results || [])
- .filter((r) => resultText(r))
- .filter((r) => !Number.isFinite(r.similarity) || r.similarity >= MIN_SIMILARITY)
- .slice(0, MAX_RESULTS);
+ const results = mergeProfileResults(
+ responses,
+ recallConfig.maxMemories,
+ ).searchResults.results;
const sessionDir = getSessionDir(input.session_id);
const seen = sessionDir ? readSeenHashes(sessionDir) : [];
const seenSet = new Set(seen);
- const fresh = results.filter((r) => !seenSet.has(hashText(resultText(r))));
+ const fresh = results.filter((result) => !seenSet.has(hashText(resultText(result))));
const repeats = results.length - fresh.length;
+ const { text: context, newFacts } = formatRecallContext(fresh, {
+ containerTag,
+ maxMemories: recallConfig.maxMemories,
+ maxTokens: recallConfig.maxPromptRecallTokens,
+ customContainers: recallConfig.autoRecallContainers
+ ? recallConfig.customContainers
+ : [],
+ });
if (input.session_id) {
const prev = readState(input.session_id).search || {};
writeState(input.session_id, 'search', {
- results: fresh.length,
+ results: newFacts.length,
count: (prev.count || 0) + 1,
- memories: (prev.memories || 0) + fresh.length,
+ memories: (prev.memories || 0) + newFacts.length,
});
}
debugLog(settings, 'Prompt recall', {
query: prompt.slice(0, 80),
+ containerTags,
hits: results.length,
- fresh: fresh.length,
+ fresh: newFacts.length,
});
- if (fresh.length === 0) {
+ if (!context) {
writeOutput({ continue: true, suppressOutput: true });
return;
}
if (sessionDir) {
try {
+ const emitted = fresh.slice(0, newFacts.length);
atomicWriteJson(
path.join(sessionDir, 'recalled.json'),
- [...seen, ...fresh.map((r) => hashText(resultText(r)))].slice(-MAX_SEEN_HASHES),
+ [...seen, ...emitted.map((result) => hashText(resultText(result)))].slice(
+ -MAX_SEEN_HASHES,
+ ),
);
} catch {
// Dedup is best effort; recall itself must still go through.
}
}
- const context = formatRecall(fresh, containerTag);
// ~4 chars/token: close enough to show what the injection costs.
const tok = gray(`(${Math.round(context.length / 4)} tok)`);
const label = repeats
- ? `recalled ${fresh.length} new ${tok}${gray(` · ${repeats} already in context`)}`
- : `recalled ${fresh.length} ${fresh.length === 1 ? 'memory' : 'memories'} ${tok}`;
+ ? `recalled ${newFacts.length} new ${tok}${gray(` · ${repeats} already in context`)}`
+ : `recalled ${newFacts.length} ${newFacts.length === 1 ? 'memory' : 'memories'} ${tok}`;
writeOutput({
systemMessage: `${BRAND} ${gray('·')} ${label}`,
hookSpecificOutput: {
diff --git a/plugin/hooks/session-start.js b/plugin/hooks/session-start.js
index 598f9d9..186f633 100644
--- a/plugin/hooks/session-start.js
+++ b/plugin/hooks/session-start.js
@@ -1,14 +1,20 @@
const fs = require('node:fs');
const path = require('node:path');
const os = require('node:os');
-const { getProfile } = require('./lib/api');
+const { getProfiles } = require('./lib/api');
const { getContainerTag, getProjectName } = require('./lib/container-tag');
+const {
+ formatSessionContext,
+ getRecallContainerTags,
+ mergeProfileResults,
+} = require('./lib/context');
const { loadProjectConfig } = require('./lib/project-config');
const {
loadSettings,
getApiKey,
getBaseUrl,
debugLog,
+ getRecallConfig,
} = require('./lib/settings');
const { BRAND, MARK, bold, gray } = require('./lib/colors');
const { readStdin, writeOutput } = require('./lib/stdin');
@@ -125,31 +131,6 @@ function welcomeBackNotice(containerTag) {
}
}
-function formatContext(profileResult, maxItems, containerTag, projectName) {
- const statics = (profileResult?.profile?.static || []).slice(0, maxItems);
- const dynamics = (profileResult?.profile?.dynamic || []).slice(0, maxItems);
- if (statics.length === 0 && dynamics.length === 0) return null;
-
- const sections = [];
- if (statics.length > 0) {
- sections.push(
- `## User Profile (Persistent)\n${statics.map((f) => `- ◪ ${f}`).join('\n')}`,
- );
- }
- if (dynamics.length > 0) {
- sections.push(
- `## Recent Context\n${dynamics.map((f) => `- ◪ ${f}`).join('\n')}`,
- );
- }
-
- return `
-Recalled memory for this project (${projectName}). Every line marked ◪ comes from supermemory — when citing one, keep the mark and phrase it naturally (e.g. "◪ last week you told me about X"). If you name the source, say "from supermemory" — never "from memory".
-This project's memory container: ${containerTag}
-
-${sections.join('\n\n')}
-`;
-}
-
function output(additionalContext, systemMessageParts) {
const systemMessage = systemMessageParts.filter(Boolean).join('\n');
writeOutput({
@@ -177,8 +158,15 @@ async function main() {
const projectConfig = loadProjectConfig(cwd);
const projectName = getProjectName(cwd);
const containerTag = getContainerTag(cwd);
+ const recallConfig = getRecallConfig(cwd);
+ const containerTags = getRecallContainerTags(containerTag, recallConfig);
- debugLog(settings, 'SessionStart', { cwd, projectName, containerTag });
+ debugLog(settings, 'SessionStart', {
+ cwd,
+ projectName,
+ containerTag,
+ containerTags,
+ });
let apiKey;
try {
@@ -205,7 +193,13 @@ Or set the SUPERMEMORY_CC_API_KEY environment variable.
let profileResult = null;
let apiError = null;
try {
- profileResult = await getProfile(baseUrl, apiKey, containerTag, projectName);
+ const responses = await getProfiles(
+ baseUrl,
+ apiKey,
+ containerTags,
+ undefined,
+ );
+ profileResult = mergeProfileResults(responses, recallConfig.maxMemories);
} catch (err) {
// Fail open, but never silently: a network failure must not be dressed
// up as "this project has no memories". Only 404 means genuinely empty.
@@ -213,15 +207,16 @@ Or set the SUPERMEMORY_CC_API_KEY environment variable.
debugLog(settings, 'Profile fetch failed', { error: err.message });
}
- const context = formatContext(
+ const { text: context, newFacts } = formatSessionContext(
profileResult,
- settings.maxProfileItems,
- containerTag,
- projectName,
+ {
+ maxProfileItems: recallConfig.maxProfileItems,
+ maxTokens: recallConfig.maxRecallTokens,
+ containerTag,
+ projectName,
+ },
);
- const loaded =
- Math.min(profileResult?.profile?.static?.length || 0, settings.maxProfileItems) +
- Math.min(profileResult?.profile?.dynamic?.length || 0, settings.maxProfileItems);
+ const loaded = newFacts.length;
writeState(sessionId, 'context', {
status: apiError ? 'error' : 'ready',
diff --git a/test/unit.mjs b/test/unit.mjs
index c883f95..49eeb05 100644
--- a/test/unit.mjs
+++ b/test/unit.mjs
@@ -31,6 +31,7 @@ const {
getStatusLabel,
renderStatusline,
} = require('../plugin/statusline.js');
+const { formatRecallContext } = require('../plugin/hooks/lib/context.js');
const HOOKS_DIR = join(process.cwd(), 'plugin', 'hooks');
@@ -221,6 +222,102 @@ describe('recall-directive hook', () => {
assert.equal(state.search.memories, 4);
});
+ test('mirrors shared Codex limits and globally ranks automatic containers', async (t) => {
+ const { repo, home } = makeRepo(t);
+ mkdirSync(join(home, '.supermemory-claude'), { recursive: true });
+ mkdirSync(join(home, '.codex'), { recursive: true });
+ writeFileSync(
+ join(home, '.supermemory-claude', 'credentials.json'),
+ JSON.stringify({ apiKey: 'sm_test_key_0123456789abcdef' }),
+ );
+ writeFileSync(
+ join(home, '.codex', 'supermemory.json'),
+ JSON.stringify({
+ maxMemories: 15,
+ maxProfileItems: 15,
+ maxRecallTokens: 5000,
+ maxPromptRecallTokens: 2000,
+ autoRecallContainers: true,
+ customContainers: [
+ { tag: 'coding_personal', description: 'Personal coding decisions.' },
+ { tag: 'copla_company', description: 'Company knowledge.' },
+ { tag: 'unavailable', description: 'Temporarily unavailable.' },
+ ],
+ }),
+ );
+ const results = {
+ coding_personal: Array.from({ length: 8 }, (_, index) => ({
+ memory: index === 0 ? 'Tomauskasz GitHub account preference' : `coding-${index}`,
+ similarity: 0.99 - index / 100,
+ })),
+ copla_company: Array.from({ length: 8 }, (_, index) => ({
+ memory: `Copla company knowledge workflow ${index}`,
+ similarity: 0.985 - index / 100,
+ })),
+ };
+ const stub = await startStubServer(t, (record, res) => {
+ const { containerTag } = JSON.parse(record.body);
+ if (containerTag === 'unavailable') {
+ res.statusCode = 503;
+ res.end('unavailable');
+ return;
+ }
+ res.setHeader('Content-Type', 'application/json');
+ res.end(
+ JSON.stringify({
+ searchResults: {
+ results:
+ results[containerTag] ||
+ Array.from({ length: 8 }, (_, index) => ({
+ memory: `repo-${index}`,
+ similarity: 0.97 - index / 100,
+ })),
+ },
+ }),
+ );
+ });
+
+ const { stdout } = await runHook(
+ 'recall-directive.js',
+ {
+ session_id: 's-shared-config',
+ cwd: repo,
+ prompt: 'recall personal GitHub preferences and Copla company workflows',
+ },
+ { HOME: home, USERPROFILE: home, SUPERMEMORY_API_URL: stub.url },
+ );
+ const context = JSON.parse(stdout).hookSpecificOutput.additionalContext;
+ const tags = stub.requests.map((request) => JSON.parse(request.body).containerTag);
+ assert.deepEqual(new Set(tags), new Set([
+ `repo_example_project__${hash16('github.com/acme/example.project')}`,
+ 'coding_personal',
+ 'copla_company',
+ 'unavailable',
+ ]));
+ assert.equal((context.match(/^- ◪ /gm) || []).length, 15);
+ assert.ok(context.indexOf('Tomauskasz') < context.indexOf('repo-0'));
+ assert.match(context, /Copla company knowledge workflow/);
+ assert.match(context, /Configured automatic recall containers:/);
+ assert.ok(context.length <= 8000);
+ assert.match(context, /<\/supermemory-recall>$/);
+ });
+
+ test('preserves complete recall wrappers at the token budget', () => {
+ const { text, newFacts } = formatRecallContext(
+ [{ memory: 'x'.repeat(4000) }],
+ {
+ containerTag: 'repo_test',
+ maxMemories: 15,
+ maxTokens: 200,
+ customContainers: [],
+ },
+ );
+ assert.ok(text.length <= 800);
+ assert.match(text, /…/);
+ assert.match(text, /<\/supermemory-recall>$/);
+ assert.equal(newFacts.length, 1);
+ });
+
test('skips trivial prompts and slash commands without an API call', async (t) => {
const { repo, home } = makeRepo(t);
mkdirSync(join(home, '.supermemory-claude'), { recursive: true });
@@ -399,6 +496,56 @@ describe('session-start hook', () => {
assert.equal(state.context.status, 'ready');
assert.equal(state.context.memoryItemsLoaded, 2);
});
+
+ test('loads profile facts from shared automatic containers', async (t) => {
+ const { repo, home } = makeRepo(t);
+ mkdirSync(join(home, '.supermemory-claude'), { recursive: true });
+ mkdirSync(join(home, '.codex'), { recursive: true });
+ writeFileSync(
+ join(home, '.supermemory-claude', 'credentials.json'),
+ JSON.stringify({ apiKey: 'sm_test_key_0123456789abcdef' }),
+ );
+ writeFileSync(
+ join(home, '.codex', 'supermemory.json'),
+ JSON.stringify({
+ maxMemories: 15,
+ maxProfileItems: 15,
+ maxRecallTokens: 5000,
+ maxPromptRecallTokens: 2000,
+ autoRecallContainers: true,
+ customContainers: [
+ { tag: 'coding_personal', description: 'Personal coding decisions.' },
+ { tag: 'copla_company', description: 'Company knowledge.' },
+ ],
+ }),
+ );
+ const stub = await startStubServer(t, (record, res) => {
+ const { containerTag } = JSON.parse(record.body);
+ res.setHeader('Content-Type', 'application/json');
+ res.end(
+ JSON.stringify({
+ profile: {
+ static: [`static:${containerTag}`],
+ dynamic: [`dynamic:${containerTag}`],
+ },
+ }),
+ );
+ });
+
+ const { stdout } = await runHook(
+ 'session-start.js',
+ { session_id: 'sess-shared-config', cwd: repo },
+ { HOME: home, USERPROFILE: home, SUPERMEMORY_API_URL: stub.url },
+ );
+ const output = JSON.parse(stdout);
+ const context = output.hookSpecificOutput.additionalContext;
+ assert.equal(stub.requests.length, 3);
+ assert.match(context, /static:coding_personal/);
+ assert.match(context, /dynamic:copla_company/);
+ assert.ok(context.length <= 20000);
+ assert.match(context, /<\/supermemory-context>$/);
+ assert.match(plain(output.systemMessage), /6 memories loaded/);
+ });
});
describe('capture hook', () => {
From 4263502b4d5c1a36fb3fe4b4184568b83ad2e270 Mon Sep 17 00:00:00 2001
From: Tomas <180413002+Tomauskasz@users.noreply.github.com>
Date: Wed, 2 Sep 2026 09:13:52 +0300
Subject: [PATCH 2/9] fix(recall): harden mirrored auto-recall
Context:
Claude now mirrors Codex recall limits, automatic containers, and the saved API endpoint when both clients use the same key. Claude-specific settings and explicit environment or project endpoint overrides remain authoritative.
Changes:
- Allowlist the six shared recall options and require a literal boolean for automatic container search.
- Globally rank and deduplicate search results, cap profile sections independently, and budget complete rendered prompt and SessionStart context.
- Track only emitted memories as seen and preserve complete wrappers when the final item is truncated.
- Prefer actionable non-404 failures when all container requests fail.
- Reuse loaded settings and project configuration across recall hooks.
- Mirror Codex's saved API base URL only for an identical active key.
- Document the shared configuration contract and add regression coverage for precedence, caps, deduplication, failure selection, endpoint matching, and context budgets.
Impact:
Claude can use the same expanded recall configuration and self-hosted Supermemory endpoint as Codex without importing unrelated Codex behavior or redirecting a different Claude credential.
Validation:
- `npm test`: 36 tests passed.
- Local marketplace `npm test`: 21 tests passed.
- Node syntax checks passed for all changed hook files.
- `npm run lint` exited successfully.
- `git diff --staged --check` passed.
- Live prompt recall returned 2,525 characters and 15 memories from both configured custom containers.
- Live SessionStart returned 4,491 characters and 30 profile facts from both configured custom containers.
Notes:
Biome reports its existing schema-version informational mismatch; no lint error was reported.
Signed-off-by: Tomas <180413002+Tomauskasz@users.noreply.github.com>
---
README.md | 9 +-
plugin/hooks/capture.js | 2 +-
plugin/hooks/lib/api.js | 5 +-
plugin/hooks/lib/context.js | 90 ++++++-----
plugin/hooks/lib/settings.js | 68 ++++----
plugin/hooks/recall-directive.js | 26 ++--
plugin/hooks/session-start.js | 12 +-
test/unit.mjs | 257 ++++++++++++++++++++++++++++---
8 files changed, 363 insertions(+), 106 deletions(-)
diff --git a/README.md b/README.md
index 59aa69a..c0b8154 100644
--- a/README.md
+++ b/README.md
@@ -85,8 +85,11 @@ SUPERMEMORY_DEBUG=true # Optional: enable debug logging
**Global Settings** — `~/.supermemory-claude/settings.json`
-Claude first loads shared recall settings from `~/.codex/supermemory.json` when
-that file exists. Claude-specific settings override the shared values.
+Claude reads only the six recall options below from
+`~/.codex/supermemory.json` when that file exists. Claude-specific settings
+override those shared values; unrelated Codex options never alter Claude.
+When both clients use the same saved API key, Claude also uses Codex's saved
+API base URL. Environment and project-specific URL overrides still take priority.
```json
{
@@ -110,7 +113,7 @@ that file exists. Claude-specific settings override the shared values.
| `maxMemories` | Maximum globally ranked prompt matches across all searched containers (default: 5) |
| `maxProfileItems` | Maximum static and dynamic profile items per section (default: 5) |
| `maxRecallTokens` | Approximate whole-context SessionStart budget (default: 2500) |
-| `maxPromptRecallTokens` | Approximate whole-context prompt-recall budget; defaults to `maxRecallTokens` |
+| `maxPromptRecallTokens` | Approximate whole-context prompt-recall budget (default: 500) |
| `autoRecallContainers` | Search every valid `customContainers` entry automatically (default: false) |
| `customContainers` | Additional recall containers with `tag` and `description` fields |
| `recallDirective` | Replace automatic prompt recall with a custom advisory instruction |
diff --git a/plugin/hooks/capture.js b/plugin/hooks/capture.js
index 90edd78..679c5b8 100644
--- a/plugin/hooks/capture.js
+++ b/plugin/hooks/capture.js
@@ -56,7 +56,7 @@ async function main() {
return;
}
- const baseUrl = getBaseUrl(cwd, projectConfig);
+ const baseUrl = getBaseUrl(cwd, projectConfig, apiKey);
const containerTag = getContainerTag(cwd);
const captured = readState(sessionId).capture?.count || 0;
diff --git a/plugin/hooks/lib/api.js b/plugin/hooks/lib/api.js
index 0c5b606..56109e8 100644
--- a/plugin/hooks/lib/api.js
+++ b/plugin/hooks/lib/api.js
@@ -61,7 +61,10 @@ async function getProfiles(baseUrl, apiKey, containerTags, query, options = {})
.filter((result) => result.status === 'fulfilled')
.map((result) => result.value);
if (profiles.length === 0) {
- throw settled.find((result) => result.status === 'rejected')?.reason;
+ const failures = settled
+ .filter((result) => result.status === 'rejected')
+ .map((result) => result.reason);
+ throw failures.find((failure) => failure?.status !== 404) || failures[0];
}
return profiles;
}
diff --git a/plugin/hooks/lib/context.js b/plugin/hooks/lib/context.js
index 571742c..2df3b03 100644
--- a/plugin/hooks/lib/context.js
+++ b/plugin/hooks/lib/context.js
@@ -39,16 +39,14 @@ function provenance(result) {
};
}
-function normalize(value) {
- return String(value || '')
- .toLowerCase()
- .trim();
+function normalizeText(value) {
+ return singleLine(value).toLowerCase();
}
function dedupe(items, keyFor) {
const seen = new Set();
return items.filter((item) => {
- const key = normalize(keyFor(item));
+ const key = normalizeText(keyFor(item));
if (!key || seen.has(key)) return false;
seen.add(key);
return true;
@@ -66,11 +64,11 @@ function mergeProfileResults(responses, maxMemories) {
responses.flatMap((response) => response?.profile?.static || []),
(fact) => fact,
);
- const staticKeys = new Set(staticFacts.map(normalize));
+ const staticKeys = new Set(staticFacts.map(normalizeText));
const dynamicFacts = dedupe(
responses.flatMap((response) => response?.profile?.dynamic || []),
(fact) => fact,
- ).filter((fact) => !staticKeys.has(normalize(fact)));
+ ).filter((fact) => !staticKeys.has(normalizeText(fact)));
const searchResults = dedupe(
responses
@@ -104,7 +102,7 @@ function getRecallContainerTags(containerTag, config) {
return [
...new Set([
containerTag,
- ...(config.autoRecallContainers
+ ...(config.autoRecallContainers === true
? config.customContainers.map((container) => container.tag.trim())
: []),
]),
@@ -123,19 +121,19 @@ function formatBoundedItems(items, maxTokens, limitName, render) {
let body = '';
const newFacts = [];
for (const item of items) {
- const fullBody = `${body}${item.before}${item.prefix}${item.text}${item.suffix}`;
+ const fullBody = `${body}${item.before}${item.text}`;
if (render(fullBody).length <= maxChars) {
body = fullBody;
- newFacts.push(item.text);
+ if (item.fact) newFacts.push(item.fact);
continue;
}
- const fixedBody = `${body}${item.before}${item.prefix}${item.suffix}`;
+ const fixedBody = `${body}${item.before}`;
const available = maxChars - render(fixedBody).length;
if (available > 1) {
- const emitted = `${item.text.slice(0, available - 1)}…`;
- body = `${body}${item.before}${item.prefix}${emitted}${item.suffix}`;
- newFacts.push(emitted);
+ const emitted = `${(item.truncateText || item.text).slice(0, available - 1)}…`;
+ body = `${fixedBody}${emitted}`;
+ if (item.fact) newFacts.push(item.fact);
}
break;
}
@@ -144,31 +142,42 @@ function formatBoundedItems(items, maxTokens, limitName, render) {
function formatRecallContext(results, options) {
const customContainers = options.customContainers || [];
- const catalog = customContainers.length
- ? `\n\nConfigured automatic recall containers:\n${customContainers
- .map(
- (container) =>
- `- ${singleLine(container.tag)}: ${singleLine(container.description)}`,
- )
- .join('\n')}`
- : '';
const render = (body) => `
◪ Recalled from supermemory for this prompt (relevance-ranked):
-${body}${catalog}
+${body}
-When one of these shapes your answer, credit it naturally with the ◪ prefix (e.g. "◪ earlier you decided X"); if you name the source, say "from supermemory" — never "from memory". For deeper history, call the supermemory search_memory tool (containerTag: "${options.containerTag}") or launch the context-gatherer agent.
+When one of these shapes your answer, credit it naturally with the ◪ prefix (e.g. "◪ earlier you decided X"); if you name the source, say "from supermemory" — never "from memory". For deeper history, call the supermemory search_memory tool or launch the context-gatherer agent.
`;
- const items = results.slice(0, Math.max(0, options.maxMemories)).map((result, index) => {
+ const items = results.map((result, index) => {
const memory = singleLine(result.memory);
const title = singleLine(result.title);
const filepath = singleLine(result.filepath);
return {
before: index === 0 ? '' : '\n',
- prefix: `- ◪ ${title && !memory.startsWith(title) ? `${title} — ` : ''}`,
- text: memory,
- suffix: filepath ? ` (${filepath})` : '',
+ fact: memory,
+ text: `- ◪ ${title && !memory.startsWith(title) ? `${title} — ` : ''}${memory}${filepath ? ` (${filepath})` : ''}`,
+ truncateText: `- ◪ ${memory}`,
};
});
+ items.push({
+ before: '\n\n',
+ fact: null,
+ text: `Recall container: ${singleLine(options.containerTag)}`,
+ });
+ if (customContainers.length) {
+ items.push({
+ before: '\n',
+ fact: null,
+ text: 'Configured automatic recall containers:',
+ });
+ items.push(
+ ...customContainers.map((container) => ({
+ before: '\n',
+ fact: null,
+ text: `- ${singleLine(container.tag)}: ${singleLine(container.description)}`,
+ })),
+ );
+ }
return formatBoundedItems(
items,
options.maxTokens,
@@ -179,8 +188,8 @@ When one of these shapes your answer, credit it naturally with the ◪ prefix (e
function formatSessionContext(result, options) {
const take = (facts) =>
- dedupe(facts, (fact) => fact)
- .map((fact) => String(fact).trim())
+ facts
+ .map((fact) => singleLine(fact))
.filter(Boolean)
.slice(0, Math.max(0, options.maxProfileItems));
const facts = [
@@ -188,17 +197,27 @@ function formatSessionContext(result, options) {
...take(result?.profile?.dynamic || []),
];
const render = (body) => `
-Recalled memory for this project (${options.projectName}). Every line marked ◪ comes from supermemory — when citing one, keep the mark and phrase it naturally. If you name the source, say "from supermemory" — never "from memory".
-This project's memory container: ${options.containerTag}
+Recalled memory for this project. Every line marked ◪ comes from supermemory — when citing one, keep the mark and phrase it naturally. If you name the source, say "from supermemory" — never "from memory".
${body}
`;
const items = facts.map((fact, index) => ({
before: index === 0 ? '[Memory Profile]\n' : '\n',
- prefix: `${index + 1}. ◪ `,
- text: fact,
- suffix: '',
+ fact,
+ text: `${index + 1}. ◪ ${fact}`,
}));
+ items.push(
+ {
+ before: '\n\n',
+ fact: null,
+ text: `Project: ${singleLine(options.projectName)}`,
+ },
+ {
+ before: '\n',
+ fact: null,
+ text: `Memory container: ${singleLine(options.containerTag)}`,
+ },
+ );
return formatBoundedItems(items, options.maxTokens, 'maxRecallTokens', render);
}
@@ -207,5 +226,6 @@ module.exports = {
formatSessionContext,
getRecallContainerTags,
mergeProfileResults,
+ normalizeText,
resultText,
};
diff --git a/plugin/hooks/lib/settings.js b/plugin/hooks/lib/settings.js
index 3c6e7df..000044e 100644
--- a/plugin/hooks/lib/settings.js
+++ b/plugin/hooks/lib/settings.js
@@ -12,13 +12,27 @@ const SHARED_SETTINGS_FILE = path.join(
'.codex',
'supermemory.json',
);
+const SHARED_CREDENTIALS_FILE = path.join(
+ os.homedir(),
+ '.codex',
+ 'supermemory',
+ 'credentials.json',
+);
+const SHARED_RECALL_KEYS = [
+ 'maxMemories',
+ 'maxProfileItems',
+ 'maxRecallTokens',
+ 'maxPromptRecallTokens',
+ 'autoRecallContainers',
+ 'customContainers',
+];
const DEFAULT_SETTINGS = {
includeTools: [],
maxMemories: 5,
maxProfileItems: 5,
maxRecallTokens: 2500,
- maxPromptRecallTokens: null,
+ maxPromptRecallTokens: 500,
autoRecallContainers: false,
customContainers: [],
debug: false,
@@ -47,18 +61,27 @@ const DEFAULT_SETTINGS = {
signalTurnsBefore: 3,
};
+function readSettings(file) {
+ try {
+ return fs.existsSync(file)
+ ? JSON.parse(fs.readFileSync(file, 'utf-8'))
+ : {};
+ } catch (err) {
+ console.error(`Settings: Failed to load ${file}: ${err.message}`);
+ return {};
+ }
+}
+
function loadSettings() {
+ const shared = readSettings(SHARED_SETTINGS_FILE);
const settings = { ...DEFAULT_SETTINGS };
- for (const file of [SHARED_SETTINGS_FILE, SETTINGS_FILE]) {
- try {
- if (fs.existsSync(file)) {
- Object.assign(settings, JSON.parse(fs.readFileSync(file, 'utf-8')));
- }
- } catch (err) {
- console.error(`Settings: Failed to load ${file}: ${err.message}`);
+ for (const key of SHARED_RECALL_KEYS) {
+ if (Object.hasOwn(shared, key)) {
+ settings[key] = shared[key];
}
}
- settings.maxPromptRecallTokens ??= settings.maxRecallTokens;
+ Object.assign(settings, readSettings(SETTINGS_FILE));
+ settings.autoRecallContainers = settings.autoRecallContainers === true;
settings.customContainers = Array.isArray(settings.customContainers)
? settings.customContainers.filter(
(container) =>
@@ -99,10 +122,18 @@ function normalizeBaseUrl(baseUrl) {
}
}
-function getBaseUrl(cwd, projectConfig) {
+function getBaseUrl(cwd, projectConfig, apiKey) {
projectConfig = projectConfig || loadProjectConfig(cwd || process.cwd());
+ const sharedCredentials = readSettings(SHARED_CREDENTIALS_FILE);
+ const sharedBaseUrl =
+ apiKey && sharedCredentials.apiKey === apiKey
+ ? sharedCredentials.apiBaseUrl
+ : null;
const configured =
- process.env.SUPERMEMORY_API_URL || projectConfig?.baseUrl || BASE_URL;
+ process.env.SUPERMEMORY_API_URL ||
+ projectConfig?.baseUrl ||
+ sharedBaseUrl ||
+ BASE_URL;
const normalized = normalizeBaseUrl(configured);
if (!normalized) {
throw new Error('Invalid baseUrl: expected an absolute http(s) URL');
@@ -162,20 +193,6 @@ function getSignalConfig(cwd) {
return { enabled, keywords, turnsBefore };
}
-function getRecallConfig(cwd) {
- const settings = loadSettings();
- const projectConfig = loadProjectConfig(cwd || process.cwd());
- return {
- directive: projectConfig?.recallDirective || settings.recallDirective || null,
- maxMemories: settings.maxMemories,
- maxProfileItems: settings.maxProfileItems,
- maxRecallTokens: settings.maxRecallTokens,
- maxPromptRecallTokens: settings.maxPromptRecallTokens,
- autoRecallContainers: settings.autoRecallContainers,
- customContainers: settings.customContainers,
- };
-}
-
module.exports = {
SETTINGS_DIR,
SETTINGS_FILE,
@@ -188,5 +205,4 @@ module.exports = {
getIncludeTools,
shouldIncludeTool,
getSignalConfig,
- getRecallConfig,
};
diff --git a/plugin/hooks/recall-directive.js b/plugin/hooks/recall-directive.js
index 7342e5d..d24ac01 100644
--- a/plugin/hooks/recall-directive.js
+++ b/plugin/hooks/recall-directive.js
@@ -9,6 +9,7 @@ const {
formatRecallContext,
getRecallContainerTags,
mergeProfileResults,
+ normalizeText,
resultText,
} = require('./lib/context');
const { getUserFriendlyError } = require('./lib/error-helpers');
@@ -18,7 +19,6 @@ const {
getApiKey,
getBaseUrl,
debugLog,
- getRecallConfig,
} = require('./lib/settings');
const {
atomicWriteJson,
@@ -49,7 +49,7 @@ function shouldSkip(prompt) {
function hashText(text) {
return crypto
.createHash('sha256')
- .update(text.replace(/\s+/g, ' ').trim())
+ .update(normalizeText(text))
.digest('hex')
.slice(0, 16);
}
@@ -74,13 +74,15 @@ async function main() {
const input = await readStdin();
const cwd = input.cwd || process.cwd();
const prompt = (input.prompt || '').trim();
- const recallConfig = getRecallConfig(cwd);
+ const projectConfig = loadProjectConfig(cwd);
+ const directive =
+ projectConfig?.recallDirective || settings.recallDirective || null;
- if (recallConfig.directive) {
+ if (directive) {
writeOutput({
hookSpecificOutput: {
hookEventName: 'UserPromptSubmit',
- additionalContext: recallConfig.directive,
+ additionalContext: directive,
},
});
return;
@@ -91,7 +93,6 @@ async function main() {
return;
}
- const projectConfig = loadProjectConfig(cwd);
let apiKey;
try {
apiKey = getApiKey(cwd, projectConfig);
@@ -101,9 +102,9 @@ async function main() {
}
const containerTag = getContainerTag(cwd);
- const containerTags = getRecallContainerTags(containerTag, recallConfig);
+ const containerTags = getRecallContainerTags(containerTag, settings);
const responses = await getProfiles(
- getBaseUrl(cwd, projectConfig),
+ getBaseUrl(cwd, projectConfig, apiKey),
apiKey,
containerTags,
prompt.slice(0, MAX_QUERY_LENGTH),
@@ -111,7 +112,7 @@ async function main() {
);
const results = mergeProfileResults(
responses,
- recallConfig.maxMemories,
+ settings.maxMemories,
).searchResults.results;
const sessionDir = getSessionDir(input.session_id);
@@ -121,10 +122,9 @@ async function main() {
const repeats = results.length - fresh.length;
const { text: context, newFacts } = formatRecallContext(fresh, {
containerTag,
- maxMemories: recallConfig.maxMemories,
- maxTokens: recallConfig.maxPromptRecallTokens,
- customContainers: recallConfig.autoRecallContainers
- ? recallConfig.customContainers
+ maxTokens: settings.maxPromptRecallTokens,
+ customContainers: settings.autoRecallContainers
+ ? settings.customContainers
: [],
});
diff --git a/plugin/hooks/session-start.js b/plugin/hooks/session-start.js
index 186f633..750b218 100644
--- a/plugin/hooks/session-start.js
+++ b/plugin/hooks/session-start.js
@@ -14,7 +14,6 @@ const {
getApiKey,
getBaseUrl,
debugLog,
- getRecallConfig,
} = require('./lib/settings');
const { BRAND, MARK, bold, gray } = require('./lib/colors');
const { readStdin, writeOutput } = require('./lib/stdin');
@@ -158,8 +157,7 @@ async function main() {
const projectConfig = loadProjectConfig(cwd);
const projectName = getProjectName(cwd);
const containerTag = getContainerTag(cwd);
- const recallConfig = getRecallConfig(cwd);
- const containerTags = getRecallContainerTags(containerTag, recallConfig);
+ const containerTags = getRecallContainerTags(containerTag, settings);
debugLog(settings, 'SessionStart', {
cwd,
@@ -188,7 +186,7 @@ Or set the SUPERMEMORY_CC_API_KEY environment variable.
}
}
- const baseUrl = getBaseUrl(cwd, projectConfig);
+ const baseUrl = getBaseUrl(cwd, projectConfig, apiKey);
let profileResult = null;
let apiError = null;
@@ -199,7 +197,7 @@ Or set the SUPERMEMORY_CC_API_KEY environment variable.
containerTags,
undefined,
);
- profileResult = mergeProfileResults(responses, recallConfig.maxMemories);
+ profileResult = mergeProfileResults(responses, settings.maxMemories);
} catch (err) {
// Fail open, but never silently: a network failure must not be dressed
// up as "this project has no memories". Only 404 means genuinely empty.
@@ -210,8 +208,8 @@ Or set the SUPERMEMORY_CC_API_KEY environment variable.
const { text: context, newFacts } = formatSessionContext(
profileResult,
{
- maxProfileItems: recallConfig.maxProfileItems,
- maxTokens: recallConfig.maxRecallTokens,
+ maxProfileItems: settings.maxProfileItems,
+ maxTokens: settings.maxRecallTokens,
containerTag,
projectName,
},
diff --git a/test/unit.mjs b/test/unit.mjs
index 49eeb05..9eb3532 100644
--- a/test/unit.mjs
+++ b/test/unit.mjs
@@ -31,7 +31,13 @@ const {
getStatusLabel,
renderStatusline,
} = require('../plugin/statusline.js');
-const { formatRecallContext } = require('../plugin/hooks/lib/context.js');
+const {
+ formatRecallContext,
+ formatSessionContext,
+ getRecallContainerTags,
+ mergeProfileResults,
+} = require('../plugin/hooks/lib/context.js');
+const { getProfiles } = require('../plugin/hooks/lib/api.js');
const HOOKS_DIR = join(process.cwd(), 'plugin', 'hooks');
@@ -140,6 +146,148 @@ function makeAuthedHome(t, apiKey = 'sm_test_key_0123456789abcdef') {
return home;
}
+function readSettings(home, apiKey = 'sm_shared') {
+ const modulePath = join(HOOKS_DIR, 'lib', 'settings.js');
+ const script = `
+ const settings = require(${JSON.stringify(modulePath)});
+ console.log(JSON.stringify({
+ settings: settings.loadSettings(),
+ signal: settings.getSignalConfig(process.cwd()),
+ includeTools: settings.getIncludeTools(process.cwd()),
+ baseUrl: settings.getBaseUrl(process.cwd(), null, ${JSON.stringify(apiKey)}),
+ }));
+ `;
+ const result = spawnSync('node', ['-e', script], {
+ encoding: 'utf-8',
+ env: { ...process.env, HOME: home, USERPROFILE: home },
+ });
+ assert.equal(result.status, 0, result.stderr);
+ return JSON.parse(result.stdout);
+}
+
+describe('recall settings and merging', () => {
+ test('shares only recall settings and applies Claude overrides', (t) => {
+ const home = makeTempDir(t, 'settings');
+ mkdirSync(join(home, '.codex'), { recursive: true });
+ mkdirSync(join(home, '.supermemory-claude'), { recursive: true });
+ writeFileSync(
+ join(home, '.codex', 'supermemory.json'),
+ JSON.stringify({
+ maxMemories: 15,
+ maxProfileItems: 15,
+ maxRecallTokens: 5000,
+ maxPromptRecallTokens: 2000,
+ autoRecallContainers: true,
+ customContainers: [{ tag: 'coding_personal', description: 'Personal.' }],
+ debug: true,
+ includeTools: ['Bash'],
+ recallDirective: 'Codex-only directive',
+ signalExtraction: true,
+ }),
+ );
+ mkdirSync(join(home, '.codex', 'supermemory'), { recursive: true });
+ writeFileSync(
+ join(home, '.codex', 'supermemory', 'credentials.json'),
+ JSON.stringify({
+ apiKey: 'sm_shared',
+ apiBaseUrl: 'http://127.0.0.1:6767',
+ }),
+ );
+ writeFileSync(
+ join(home, '.supermemory-claude', 'settings.json'),
+ JSON.stringify({ maxMemories: 2 }),
+ );
+
+ const loaded = readSettings(home);
+ assert.equal(loaded.settings.maxMemories, 2);
+ assert.equal(loaded.settings.maxProfileItems, 15);
+ assert.equal(loaded.settings.maxRecallTokens, 5000);
+ assert.equal(loaded.settings.maxPromptRecallTokens, 2000);
+ assert.equal(loaded.settings.autoRecallContainers, true);
+ assert.equal(loaded.settings.debug, false);
+ assert.equal(loaded.settings.recallDirective, null);
+ assert.equal(loaded.signal.enabled, false);
+ assert.deepEqual(loaded.includeTools, []);
+ assert.equal(loaded.baseUrl, 'http://127.0.0.1:6767');
+ assert.equal(readSettings(home, 'sm_other').baseUrl, 'https://api.supermemory.ai');
+ });
+
+ test('requires a literal boolean to search custom containers', () => {
+ const customContainers = [{ tag: 'coding_personal', description: 'Personal.' }];
+ assert.deepEqual(
+ getRecallContainerTags('repo_test', {
+ autoRecallContainers: 'false',
+ customContainers,
+ }),
+ ['repo_test'],
+ );
+ assert.deepEqual(
+ getRecallContainerTags('repo_test', {
+ autoRecallContainers: true,
+ customContainers,
+ }),
+ ['repo_test', 'coding_personal'],
+ );
+ });
+
+ test('dedupes whitespace-equivalent results before the global cap', () => {
+ const merged = mergeProfileResults(
+ [
+ { searchResults: { results: [{ memory: 'Use the shared\nsettings loader', similarity: 0.9 }] } },
+ { searchResults: { results: [{ memory: 'Use the shared settings loader', similarity: 0.8 }] } },
+ ],
+ 15,
+ );
+ assert.equal(merged.searchResults.results.length, 1);
+ });
+
+ test('caps static and dynamic profile facts independently', () => {
+ const merged = mergeProfileResults(
+ [{ profile: { static: ['s1', 's2', 's3'], dynamic: ['d1', 'd2', 'd3'] } }],
+ 15,
+ );
+ const { newFacts } = formatSessionContext(merged, {
+ maxProfileItems: 2,
+ maxTokens: 1000,
+ containerTag: 'repo_test',
+ projectName: 'Test',
+ });
+ assert.deepEqual(newFacts, ['s1', 's2', 'd1', 'd2']);
+ });
+
+ test('keeps SessionStart wrappers complete at the whole-context budget', () => {
+ const { text, newFacts } = formatSessionContext(
+ { profile: { static: ['x'.repeat(4000)], dynamic: [] } },
+ {
+ maxProfileItems: 15,
+ maxTokens: 120,
+ containerTag: 'repo_test',
+ projectName: 'Test',
+ },
+ );
+ assert.ok(text.length <= 480);
+ assert.match(text, /…/);
+ assert.match(text, /<\/supermemory-context>$/);
+ assert.equal(newFacts.length, 1);
+ });
+
+ test('surfaces a non-404 failure when every container request fails', async (t) => {
+ const stub = await startStubServer(t, (record, res) => {
+ const { containerTag } = JSON.parse(record.body);
+ res.statusCode = containerTag === 'missing' ? 404 : 503;
+ res.end(containerTag);
+ });
+ await assert.rejects(
+ getProfiles(stub.url, 'sm_test', ['missing', 'unavailable']),
+ (error) => error.status === 503,
+ );
+ await assert.rejects(
+ getProfiles(stub.url, 'sm_test', ['missing']),
+ (error) => error.status === 404,
+ );
+ });
+});
+
describe('container tags', () => {
test('derives one canonical repo tag from the git remote', (t) => {
const { repo, home } = makeRepo(t);
@@ -223,19 +371,13 @@ describe('recall-directive hook', () => {
});
test('mirrors shared Codex limits and globally ranks automatic containers', async (t) => {
- const { repo, home } = makeRepo(t);
- mkdirSync(join(home, '.supermemory-claude'), { recursive: true });
+ const { repo } = makeRepo(t);
+ const home = makeAuthedHome(t);
mkdirSync(join(home, '.codex'), { recursive: true });
- writeFileSync(
- join(home, '.supermemory-claude', 'credentials.json'),
- JSON.stringify({ apiKey: 'sm_test_key_0123456789abcdef' }),
- );
writeFileSync(
join(home, '.codex', 'supermemory.json'),
JSON.stringify({
maxMemories: 15,
- maxProfileItems: 15,
- maxRecallTokens: 5000,
maxPromptRecallTokens: 2000,
autoRecallContainers: true,
customContainers: [
@@ -304,20 +446,101 @@ describe('recall-directive hook', () => {
test('preserves complete recall wrappers at the token budget', () => {
const { text, newFacts } = formatRecallContext(
- [{ memory: 'x'.repeat(4000) }],
+ [{
+ memory: 'short memory',
+ title: 't'.repeat(4000),
+ filepath: 'p'.repeat(4000),
+ }],
{
containerTag: 'repo_test',
- maxMemories: 15,
maxTokens: 200,
- customContainers: [],
+ customContainers: [
+ { tag: 'coding_personal', description: 'd'.repeat(4000) },
+ ],
},
);
assert.ok(text.length <= 800);
+ assert.match(text, /short memory/);
assert.match(text, /…/);
assert.match(text, /<\/supermemory-recall>$/);
assert.equal(newFacts.length, 1);
});
+ test('budgets the automatic-container catalog as variable context', () => {
+ const { text, newFacts } = formatRecallContext(
+ [{ memory: 'short memory' }],
+ {
+ containerTag: 'repo_test',
+ maxTokens: 200,
+ customContainers: [
+ { tag: 'coding_personal', description: 'd'.repeat(4000) },
+ ],
+ },
+ );
+ assert.ok(text.length <= 800);
+ assert.match(text, /short memory/);
+ assert.match(text, /Configured automatic recall containers:/);
+ assert.match(text, /…/);
+ assert.match(text, /<\/supermemory-recall>$/);
+ assert.equal(newFacts.length, 1);
+ });
+
+ test('keeps the compatibility prompt budget when settings are absent', async (t) => {
+ const { repo } = makeRepo(t);
+ const home = makeAuthedHome(t);
+ const stub = await startStubServer(t, (record, res) => {
+ res.setHeader('Content-Type', 'application/json');
+ res.end(JSON.stringify({
+ searchResults: {
+ results: Array.from({ length: 5 }, (_, index) => ({
+ memory: `${index}:${'x'.repeat(4000)}`,
+ similarity: 0.9 - index / 100,
+ })),
+ },
+ }));
+ });
+
+ const { stdout } = await runHook(
+ 'recall-directive.js',
+ { session_id: 's-default-budget', cwd: repo, prompt: 'recall the previous implementation' },
+ { HOME: home, USERPROFILE: home, SUPERMEMORY_API_URL: stub.url },
+ );
+ const context = JSON.parse(stdout).hookSpecificOutput.additionalContext;
+ assert.ok(context.length <= 2000);
+ assert.match(context, /<\/supermemory-recall>$/);
+ });
+
+ test('marks only memories emitted within the prompt budget as seen', async (t) => {
+ const { repo } = makeRepo(t);
+ const home = makeAuthedHome(t);
+ writeFileSync(
+ join(home, '.supermemory-claude', 'settings.json'),
+ JSON.stringify({ maxMemories: 3, maxPromptRecallTokens: 150 }),
+ );
+ const hits = ['A', 'B', 'C'].map((prefix, index) => ({
+ memory: `${prefix}:${prefix.repeat(1000)}`,
+ similarity: 0.9 - index / 100,
+ }));
+ const stub = await startStubServer(t, (record, res) => {
+ res.setHeader('Content-Type', 'application/json');
+ res.end(JSON.stringify({ searchResults: { results: hits } }));
+ });
+ const input = {
+ session_id: 's-emitted-only',
+ cwd: repo,
+ prompt: 'recall the long ordered memories',
+ };
+ const env = { HOME: home, USERPROFILE: home, SUPERMEMORY_API_URL: stub.url };
+
+ const first = JSON.parse((await runHook('recall-directive.js', input, env)).stdout);
+ assert.match(first.hookSpecificOutput.additionalContext, /A:AAA/);
+ assert.doesNotMatch(first.hookSpecificOutput.additionalContext, /B:BBB/);
+
+ const second = JSON.parse((await runHook('recall-directive.js', input, env)).stdout);
+ assert.match(second.hookSpecificOutput.additionalContext, /B:BBB/);
+ assert.doesNotMatch(second.hookSpecificOutput.additionalContext, /A:AAA/);
+ });
+
test('skips trivial prompts and slash commands without an API call', async (t) => {
const { repo, home } = makeRepo(t);
mkdirSync(join(home, '.supermemory-claude'), { recursive: true });
@@ -498,20 +721,14 @@ describe('session-start hook', () => {
});
test('loads profile facts from shared automatic containers', async (t) => {
- const { repo, home } = makeRepo(t);
- mkdirSync(join(home, '.supermemory-claude'), { recursive: true });
+ const { repo } = makeRepo(t);
+ const home = makeAuthedHome(t);
mkdirSync(join(home, '.codex'), { recursive: true });
- writeFileSync(
- join(home, '.supermemory-claude', 'credentials.json'),
- JSON.stringify({ apiKey: 'sm_test_key_0123456789abcdef' }),
- );
writeFileSync(
join(home, '.codex', 'supermemory.json'),
JSON.stringify({
- maxMemories: 15,
maxProfileItems: 15,
maxRecallTokens: 5000,
- maxPromptRecallTokens: 2000,
autoRecallContainers: true,
customContainers: [
{ tag: 'coding_personal', description: 'Personal coding decisions.' },
From 07af87ac4301066228e3f331a966af2f03468af3 Mon Sep 17 00:00:00 2001
From: Tomas <180413002+Tomauskasz@users.noreply.github.com>
Date: Wed, 2 Sep 2026 10:29:01 +0300
Subject: [PATCH 3/9] fix(recall): harden shared config
Context:
Shared Codex configuration and credentials now fail open at the optional-file boundary without exposing parser input, and bounded recall records only memory text that reached the emitted context.
Changes:
- Validate shared JSON as a non-array object and redact parse diagnostics.
- Ignore invalid mirrored endpoints, preserve explicit endpoint precedence, and normalize Codex-valid custom containers with empty descriptions.
- Track truncated facts only after fact content is emitted.
- Route the status command through the runtime credential and endpoint resolvers and remove the inspector's stale directive projection.
- Add credential, endpoint, capture, status, deduplication, and minimum-budget coverage, split across focused test files with shared fixtures.
Impact:
Malformed optional Codex files no longer disable Claude recall or capture. Matching credentials reuse only valid mirrored endpoints. Status probes the same endpoint as recall and writes. Prefix-only context cannot suppress an un-emitted memory.
Validation:
- `npm test`: 44 tests passed.
- `npx biome ci .`: passed.
- Node syntax checks passed for changed JavaScript and test modules.
- Bun bundled `plugin-inspector.ts` successfully.
- `git diff --staged --check`: passed.
Notes:
None.
---
package.json | 2 +-
plugin-inspector.ts | 7 +-
plugin/commands/status.md | 15 +-
plugin/hooks/lib/context.js | 25 +-
plugin/hooks/lib/settings.js | 33 +-
plugin/hooks/status-check.js | 49 ++
test/helpers.mjs | 96 ++++
test/recall.mjs | 912 +++++++++++++++++++++++++++++++++++
test/unit.mjs | 732 +---------------------------
9 files changed, 1110 insertions(+), 761 deletions(-)
create mode 100644 plugin/hooks/status-check.js
create mode 100644 test/helpers.mjs
create mode 100644 test/recall.mjs
diff --git a/package.json b/package.json
index 8a88868..631ad3e 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
"private": true,
"type": "commonjs",
"scripts": {
- "test": "node --test test/unit.mjs",
+ "test": "node --test test/unit.mjs test/recall.mjs",
"lint": "biome check .",
"lint:fix": "biome check --write .",
"format": "biome format --write ."
diff --git a/plugin-inspector.ts b/plugin-inspector.ts
index ecbdf53..0bf3000 100644
--- a/plugin-inspector.ts
+++ b/plugin-inspector.ts
@@ -62,8 +62,6 @@ async function inspect() {
}),
);
- const directiveSrc = await Bun.file(join(PLUGIN, "hooks/recall-directive.js")).text();
- const directive = directiveSrc.match(/return `([\s\S]*?)`;/)?.[1] ?? "";
const approveSrc = await Bun.file(join(PLUGIN, "hooks/recall-approve.js")).text();
const readOnlyTools = [...approveSrc.matchAll(/^\s*'([\w-]+)',$/gm)].map((m) => m[1]);
@@ -82,7 +80,6 @@ async function inspect() {
hooks,
commands,
agents,
- directive,
readOnlyTools,
files: listFiles(PLUGIN),
};
@@ -123,7 +120,6 @@ const html = `
hooks
mcp server + auto-approved (read-only) tools
-recall directive — injected every prompt
agents
commands
plugin files (all committed source, no build)
@@ -132,7 +128,7 @@ const esc = s => String(s).replace(/[&<>]/g, c => ({'&':'&','<':'<','>':'
const kb = n => n < 1024 ? n + ' b' : (n / 1024).toFixed(1) + ' kb';
const HOOK_NOTES = {
SessionStart: 'profile fetch → context + "N memories loaded" + welcome-back; auth bootstrap; statusline symlink upkeep',
- UserPromptSubmit: 'injects recall directive with active container tag (local, no network)',
+ UserPromptSubmit: 'bounded automatic recall from the active and configured containers',
PreToolUse: 'auto-approves read-only supermemory MCP tools + "recalling: " message',
Stop: 'captures transcript delta with entityContext; writes statusline state',
};
@@ -153,7 +149,6 @@ fetch('/api/inspect').then(r => r.json()).then(d => {
'server "' + esc(server[0]) + '": ' + esc(server[1].command + ' ' + server[1].args.join(' ')) +
' (proxy \\u2192 mcp.supermemory.ai, authed via credentials.json)
' +
d.readOnlyTools.map(t => '' + esc(t) + '').join('');
- document.getElementById('directive').textContent = d.directive;
const fileSection = items => items.map(i =>
'' + esc(i.name) + '' + esc(i.description) + '
' + esc(i.content) + '