@vantran-se/openchamber-web 1.24.3 → 2.0.1

package/server/lib/session-knowledge/DOCUMENTATION.md

@@ -52,6 +52,11 @@ Nothing here may fail a send. A message without its background costs the agent
 some context; a failed send costs the user their message. Every caller treats an
 error as "no block this time".
 
+While memory is on, every session is told when to save, even with an empty
+store. The tool description alone is read only when the agent already means to
+call it, so agents told nothing here saved only when the user said "remember".
+The session hears "nothing is stored yet" only when both scopes loaded.
+
 A source that will not load never blanks the rest: an unreadable memory store
 still delivers the pinned notes. A memory scope that failed to load is left out
 rather than indexed as empty, which would teach the agent to store again what it

package/server/lib/session-knowledge/runtime.js

@@ -37,6 +37,9 @@ export const buildKnowledgeSignature = ({ notes, plans, memory }) => {
     ...plans.map((plan) => `p:${plan.id}:${plan.title}`),
     ...memory.global.map((entry) => `mg:${entry.id}:${entry.updatedAt}`),
     ...memory.project.map((entry) => `mp:${entry.id}:${entry.updatedAt}`),
+    // Memory being on is itself worth telling a session: without it an empty
+    // store sends nothing, and an agent never told when to save never does.
+    ...(memory.enabled ? [`m:on:${memory.complete ? 'c' : 'p'}`] : []),
   ];
   return parts.length === 0 ? '' : parts.sort().join('|');
 };
@@ -47,24 +50,46 @@ const renderMemorySection = (entries) => entries
   .map((entry) => `- [${entry.type}] ${entry.title}`)
   .join('\n');
 
+/**
+ * When to save, stated in every session where memory is on. The tool
+ * description alone is read only when the agent already means to call it, so
+ * agents told nothing here saved only when the user said "remember".
+ */
+const MEMORY_SAVE_GUIDANCE = 'You have memory that persists across sessions, through the'
+  + ' openchamber_memory tool. Save to it in the moment, without asking first, when:'
+  + ' the user corrects how you work or states a preference; the user confirms that'
+  + ' a non-obvious approach worked; or you learn a project fact that took real'
+  + ' effort to find and is not in the code or docs. One fact per entry. The user'
+  + ' can review and remove what you save, so save when it fits and mention it'
+  + ' briefly.';
+
 /**
  * Titles only for memory, never bodies: an index carrying full text grows
  * without bound until it crowds out the conversation it was meant to inform.
  */
-const buildMemoryBlock = ({ global, project }) => {
+const buildMemoryBlock = ({ global, project, enabled = false, complete = false }) => {
   const sections = [];
   if (global.length > 0) sections.push(`### About the user\n\n${renderMemorySection(global)}`);
   if (project.length > 0) sections.push(`### About this project\n\n${renderMemorySection(project)}`);
-  if (sections.length === 0) return '';
+  if (sections.length === 0) {
+    if (!enabled) return '';
+    // "Empty" only when both scopes loaded: a failed read is not an empty store.
+    return complete
+      ? `${MEMORY_SAVE_GUIDANCE}\n\nNothing is stored yet.`
+      : MEMORY_SAVE_GUIDANCE;
+  }
 
   return [
-    'You have stored memory from earlier sessions. Only the titles are listed below.',
+    ...(enabled ? [MEMORY_SAVE_GUIDANCE] : []),
+    'Stored memory from earlier sessions: only the titles are listed below.',
     'A title is an abbreviation, not the memory. Read the entry with the'
       + ' openchamber_memory tool before you act on it: titles routinely leave out'
       + ' the conditions, exceptions and reasons that decide how the memory'
       + ' applies, and a title that looks self-explanatory is the most likely to'
       + ' be hiding them. Read every title that could bear on the task at hand;'
-      + ' you need not read the ones unrelated to what you are doing.',
+      + ' you need not read the ones unrelated to what you are doing. Read each'
+      + ' entry once per conversation: what you read stays in your context, so do'
+      + ' not read it again on later turns unless your context was summarized.',
     'Memory records what was true when it was written. Verify anything it says'
       + ' about files, flags or commands before relying on it.',
     ...sections,
@@ -112,9 +137,21 @@ export const createSessionKnowledgeRuntime = (dependencies) => {
     agentMemoryRuntime,
     resolveProjectId,
     isAgentMemoryEnabled,
-    openCodeFetch = null,
+    // Pins and the delivered-signature cursor live in OpenChamber's own session
+    // metadata store: OpenCode 2.x accepts session metadata only at create time.
+    readSessionMetadata = null,
+    persistSessionMetadata = null,
   } = dependencies;
 
+  const requireMetadataStore = () => {
+    if (typeof readSessionMetadata !== 'function' || typeof persistSessionMetadata !== 'function') {
+      throw new Error('project knowledge needs a session metadata store');
+    }
+  };
+
+  /** The session shape the readers below expect, built from our own store. */
+  const readStoredSession = async (sessionId) => ({ metadata: await readSessionMetadata(sessionId) });
+
   /**
    * Everything the session should be carrying, read fresh. A failure in one
    * source never blanks the rest: a memory store that will not load must not
@@ -156,7 +193,7 @@ export const createSessionKnowledgeRuntime = (dependencies) => {
       }
     }
 
-    let memory = { global: [], project: [] };
+    let memory = { global: [], project: [], enabled: false, complete: false };
     const memoryEnabled = typeof isAgentMemoryEnabled === 'function'
       ? await isAgentMemoryEnabled().catch(() => false)
       : true;
@@ -173,9 +210,11 @@ export const createSessionKnowledgeRuntime = (dependencies) => {
         memory = {
           global: stored.globalFailed ? [] : visible(stored.global),
           project: stored.projectFailed ? [] : visible(stored.project),
+          enabled: true,
+          complete: !stored.globalFailed && !stored.projectFailed,
         };
       } catch {
-        memory = { global: [], project: [] };
+        memory = { global: [], project: [], enabled: true, complete: false };
       }
     }
 
@@ -247,44 +286,32 @@ export const createSessionKnowledgeRuntime = (dependencies) => {
     return { text: buildKnowledgeText(collected), signature };
   };
 
-  const readSession = async (sessionId, directory) => (
-    openCodeFetch(`/session/${encodeURIComponent(sessionId)}`, { directory })
-  );
-
   /**
    * What this session still owes, read from its own stored signature.
    */
   const resolvePendingForSession = async (sessionId, directory) => {
-    const session = await readSession(sessionId, directory).catch(() => null);
+    const session = await readStoredSession(sessionId).catch(() => null);
     return resolvePending(directory, readDeliveredSignature(session), readPins(session));
   };
 
   const collectSummaryForSession = async (sessionId, directory) => {
-    const session = await readSession(sessionId, directory).catch(() => null);
+    const session = await readStoredSession(sessionId).catch(() => null);
     return collectSummary(directory, readPins(session));
   };
 
   const setPin = async (sessionId, directory, kind, id, pinned) => {
-    const fresh = await readSession(sessionId, directory);
-    const metadata = isRecord(fresh?.metadata) ? fresh.metadata : {};
-    const openchamber = isRecord(metadata.openchamber) ? metadata.openchamber : {};
-    const pins = readPins(fresh);
+    requireMetadataStore();
+    const pins = readPins(await readStoredSession(sessionId));
     const key = kind === 'note' ? 'notes' : 'plans';
     const next = new Set(pins[key]);
     if (pinned) next.add(id);
     else next.delete(id);
-    await openCodeFetch(`/session/${encodeURIComponent(sessionId)}`, {
-      directory,
-      method: 'PATCH',
-      body: {
-        metadata: {
-          ...metadata,
-          openchamber: {
-            ...openchamber,
-            [PINS_METADATA_KEY]: { ...pins, [key]: [...next] },
-            [KNOWLEDGE_METADATA_KEY]: '',
-          },
-        },
+    // Clearing the delivered signature is what makes the next send carry the
+    // changed pin set; the merge patch leaves neighbouring state alone.
+    await persistSessionMetadata(sessionId, directory, {
+      openchamber: {
+        [PINS_METADATA_KEY]: { ...pins, [key]: [...next] },
+        [KNOWLEDGE_METADATA_KEY]: '',
       },
     });
     return { ...pins, [key]: [...next] };
@@ -300,18 +327,9 @@ export const createSessionKnowledgeRuntime = (dependencies) => {
    * drop whatever changed in between.
    */
   const recordDelivered = async (sessionId, directory, signature) => {
-    const fresh = await readSession(sessionId, directory);
-    const metadata = isRecord(fresh?.metadata) ? fresh.metadata : {};
-    const openchamber = isRecord(metadata.openchamber) ? metadata.openchamber : {};
-    await openCodeFetch(`/session/${encodeURIComponent(sessionId)}`, {
-      directory,
-      method: 'PATCH',
-      body: {
-        metadata: {
-          ...metadata,
-          openchamber: { ...openchamber, [KNOWLEDGE_METADATA_KEY]: signature },
-        },
-      },
+    requireMetadataStore();
+    await persistSessionMetadata(sessionId, directory, {
+      openchamber: { [KNOWLEDGE_METADATA_KEY]: signature },
     });
   };
 

package/server/lib/session-knowledge/runtime.test.js

@@ -27,10 +27,26 @@ const createRuntime = (overrides = {}) => createSessionKnowledgeRuntime({
     readAll: async () => ({ global: [memory()], project: [], globalFailed: false, projectFailed: false }),
     ...overrides.agentMemoryRuntime,
   },
-  ...('openCodeFetch' in overrides ? { openCodeFetch: overrides.openCodeFetch } : {}),
+  ...('readSessionMetadata' in overrides ? { readSessionMetadata: overrides.readSessionMetadata } : {}),
+  ...('persistSessionMetadata' in overrides ? { persistSessionMetadata: overrides.persistSessionMetadata } : {}),
   ...('isAgentMemoryEnabled' in overrides ? { isAgentMemoryEnabled: overrides.isAgentMemoryEnabled } : {}),
 });
 
+/** An in-memory stand-in for `session-metadata-store.js`. */
+const createMetadataStub = (initial = {}) => {
+  const state = { ...initial };
+  const patches = [];
+  return {
+    patches,
+    readSessionMetadata: async (sessionId) => state[sessionId] ?? {},
+    persistSessionMetadata: async (sessionId, directory, patch) => {
+      patches.push({ sessionId, directory, patch });
+      const openchamber = { ...(state[sessionId]?.openchamber ?? {}), ...(patch.openchamber ?? {}) };
+      state[sessionId] = { ...(state[sessionId] ?? {}), openchamber };
+    },
+  };
+};
+
 describe('what the session is owed', () => {
   test('carries pinned notes, pinned plan bodies, and the memory index', async () => {
     const { text } = await createRuntime().resolvePending(DIRECTORY, '', PINS);
@@ -59,12 +75,10 @@ describe('what the session is owed', () => {
     expect(text).not.toContain('Pinned note body.');
   });
 
-  test('nothing pinned and nothing remembered owes nothing', async () => {
+  test('nothing pinned with memory off owes nothing', async () => {
     const runtime = createRuntime({
       projectContextRuntime: { readContext: async () => ({ notes: [], todos: [], plans: [] }) },
-      agentMemoryRuntime: {
-        readAll: async () => ({ global: [], project: [], globalFailed: false, projectFailed: false }),
-      },
+      isAgentMemoryEnabled: async () => false,
     });
 
     const { text, signature } = await runtime.resolvePending(DIRECTORY, '');
@@ -72,6 +86,35 @@ describe('what the session is owed', () => {
     expect(signature).toBe('');
     expect(text).toBe('');
   });
+
+  test('an empty memory store still tells the session when to save', async () => {
+    const runtime = createRuntime({
+      projectContextRuntime: { readContext: async () => ({ notes: [], todos: [], plans: [] }) },
+      agentMemoryRuntime: {
+        readAll: async () => ({ global: [], project: [], globalFailed: false, projectFailed: false }),
+      },
+    });
+
+    const first = await runtime.resolvePending(DIRECTORY, '');
+    expect(first.text).toContain('Save to it in the moment');
+    expect(first.text).toContain('Nothing is stored yet.');
+
+    const again = await runtime.resolvePending(DIRECTORY, first.signature);
+    expect(again.text).toBe('');
+  });
+
+  test('a memory store that failed to load is not called empty', async () => {
+    const runtime = createRuntime({
+      projectContextRuntime: { readContext: async () => ({ notes: [], todos: [], plans: [] }) },
+      agentMemoryRuntime: {
+        readAll: async () => ({ global: [], project: [], globalFailed: true, projectFailed: false }),
+      },
+    });
+
+    const { text } = await runtime.resolvePending(DIRECTORY, '');
+    expect(text).toContain('Save to it in the moment');
+    expect(text).not.toContain('Nothing is stored yet.');
+  });
 });
 
 describe('what has already been delivered', () => {
@@ -201,25 +244,52 @@ describe('reading what a session was told', () => {
     expect(runtime.readPins({})).toEqual({ notes: [], plans: [] });
   });
 
-  test('pinning updates only the target session and invalidates its delivered signature', async () => {
-    const requests = [];
-    const runtime = createRuntime({
-      openCodeFetch: async (path, options = {}) => {
-        requests.push({ path, options });
-        if (options.method === 'PATCH') return {};
-        return {
-          metadata: { openchamber: { project_context_pins: { notes: [], plans: [] }, knowledge_context_delivered: 'old' } },
-        };
+  test('pins into OpenChamber\'s own store and invalidates the delivered signature', async () => {
+    const store = createMetadataStub({
+      ses_a: { openchamber: { project_context_pins: { notes: [], plans: [] }, knowledge_context_delivered: 'old' } },
+    });
+    const runtime = createRuntime(store);
+
+    await expect(runtime.setPin('ses_a', DIRECTORY, 'note', 'n1', true)).resolves.toEqual({ notes: ['n1'], plans: [] });
+
+    expect(store.patches).toEqual([{
+      sessionId: 'ses_a',
+      directory: DIRECTORY,
+      patch: {
+        openchamber: {
+          project_context_pins: { notes: ['n1'], plans: [] },
+          knowledge_context_delivered: '',
+        },
       },
+    }]);
+  });
+
+  test('unpins the same way', async () => {
+    const store = createMetadataStub({
+      ses_a: { openchamber: { project_context_pins: { notes: ['n1', 'n2'], plans: [] } } },
     });
+    const runtime = createRuntime(store);
+
+    await expect(runtime.setPin('ses_a', DIRECTORY, 'note', 'n1', false)).resolves.toEqual({ notes: ['n2'], plans: [] });
+  });
 
-    await runtime.setPin('ses_a', DIRECTORY, 'note', 'n1', true);
+  test('records delivery as a merge patch, leaving neighbouring state alone', async () => {
+    const store = createMetadataStub();
+    const runtime = createRuntime(store);
 
-    expect(requests.map((request) => request.path)).toEqual(['/session/ses_a', '/session/ses_a']);
-    expect(requests[1].options.body.metadata.openchamber).toEqual({
-      project_context_pins: { notes: ['n1'], plans: [] },
-      knowledge_context_delivered: '',
-    });
+    await runtime.recordDelivered('ses_a', DIRECTORY, 'sig-1');
+
+    expect(store.patches).toEqual([{
+      sessionId: 'ses_a',
+      directory: DIRECTORY,
+      patch: { openchamber: { knowledge_context_delivered: 'sig-1' } },
+    }]);
+  });
+
+  test('says so plainly when no metadata store is wired', async () => {
+    const runtime = createRuntime();
+    await expect(runtime.setPin('ses_a', DIRECTORY, 'note', 'n1', true)).rejects.toThrow(/session metadata store/);
+    await expect(runtime.recordDelivered('ses_a', DIRECTORY, 'sig')).rejects.toThrow(/session metadata store/);
   });
 
   test('finds the signature stored on the session', () => {