agent-writeback-note-quality-gate

Enforce structured memory writeback quality gate

Author: ZengLiangYi

server/src/cli/client.ts

@@ -6,6 +6,8 @@ import type {
   DeleteNoteReviewResponse,
   RecallForTaskRequest,
   RecallForTaskResponse,
+  ValidateTaskMemoryRequest,
+  ValidateTaskMemoryResponse,
   WriteTaskMemoryRequest,
   WriteTaskMemoryResponse,
 } from '@chatcrystal/shared';
@@ -352,6 +354,14 @@ export class CrystalClient {
     return this.request<RecallForTaskResponse>('POST', '/api/memory/recall', body);
   }
 
+  async validateTaskMemory(body: ValidateTaskMemoryRequest) {
+    return this.request<ValidateTaskMemoryResponse>(
+      'POST',
+      '/api/memory/validate',
+      body,
+    );
+  }
+
   async writeTaskMemory(body: WriteTaskMemoryRequest) {
     return this.request<WriteTaskMemoryResponse>(
       'POST',

server/src/cli/mcp/server.ts

@@ -4,6 +4,7 @@ import { z } from 'zod';
 import { CrystalClient } from '../client.js';
 import {
   RecallForTaskRequestShape,
+  ValidateTaskMemoryRequestShape,
   WriteTaskMemoryRequestShape,
 } from '../../services/memory/schemas.js';
 
@@ -106,9 +107,24 @@ export async function startMcpServer(baseUrl: string) {
     },
   );
 
+  server.tool(
+    'validate_task_memory',
+    'Preflight a task memory candidate without side effects. Use this before write_task_memory when available. Returns materialized ChatCrystal note fields, acceptance, reason, and warnings.',
+    ValidateTaskMemoryRequestShape,
+    async (input) => {
+      const data = await client.validateTaskMemory(input);
+      return {
+        content: [{
+          type: 'text' as const,
+          text: JSON.stringify(data, null, 2),
+        }],
+      };
+    },
+  );
+
   server.tool(
     'write_task_memory',
-    'Persist a task memory with idempotent auto-writeback semantics.',
+    'Persist a task memory only when it can become a high-quality ChatCrystal note: specific title, concrete summary, meaningful key conclusions, and a durable reusable lesson such as a pitfall, fix, decision, pattern, or symptom-to-resolution mapping. Do not write one-time environment checks, version/status reports, ordinary progress logs, or vague robustness claims. Weak auto writebacks are skipped by core validation and recorded only as receipts.',
     WriteTaskMemoryRequestShape,
     async (input) => {
       const data = await client.writeTaskMemory(input);

server/src/routes/memory.ts

@@ -1,5 +1,6 @@
 import type { FastifyInstance } from 'fastify';
 import { ZodError } from 'zod';
+import { validateTaskMemory } from '../services/memory/preflight.js';
 import { recallForTask } from '../services/memory/recall.js';
 import { writeTaskMemory } from '../services/memory/writeback.js';
 
@@ -20,6 +21,22 @@ export async function memoryRoutes(app: FastifyInstance) {
     }
   });
 
+  app.post('/api/memory/validate', async (req, reply) => {
+    try {
+      const data = validateTaskMemory(req.body);
+      return { success: true, data };
+    } catch (error) {
+      reply.status(error instanceof ZodError ? 400 : 500);
+      return {
+        success: false,
+        error:
+          error instanceof Error
+            ? error.message
+            : 'Invalid memory validation request',
+      };
+    }
+  });
+
   app.post('/api/memory/writeback', async (req, reply) => {
     try {
       const data = await writeTaskMemory(req.body);

server/src/services/embedding.test.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import test from 'node:test';
 import { LocalIndex } from 'vectra';
 import {
+  buildNoteEmbeddingText,
   committedVectraIdsForNote,
   currentVectraIdsCommitted,
   deleteVectraItemsForNote,
@@ -17,6 +18,117 @@ function createTempDir() {
   return mkdtempSync(join(tmpdir(), 'chatcrystal-embedding-'));
 }
 
+test('buildNoteEmbeddingText includes structured agent writeback memory signals', () => {
+  const text = buildNoteEmbeddingText({
+    title: 'Server readiness race causes ECONNREFUSED',
+    summary: 'Requests must wait for server readiness before client calls.',
+    keyConclusionsJson: JSON.stringify([
+      'Await readiness before issuing HTTP requests.',
+      'Visible key conclusions stay searchable.',
+    ]),
+    codeSnippetsJson: JSON.stringify([
+      { description: 'Readiness helper wraps Fastify startup.' },
+      { code: 'console.log("code-only body remains searchable")' },
+    ]),
+    tagsText: 'readiness testing',
+    sourceType: 'agent-writeback',
+    rawPayloadJson: JSON.stringify({
+      root_cause: 'Client calls raced server startup.',
+      resolution: 'Block request setup until server readiness resolves.',
+      pitfalls: ['Do not fire API requests before Fastify ready.'],
+      reusable_patterns: ['Share a readiness helper across HTTP tests.'],
+      decisions: ['Keep readiness helper in test utilities.'],
+    }),
+    errorSignaturesJson: JSON.stringify(['ECONNREFUSED 127.0.0.1:3721']),
+    filesTouchedJson: JSON.stringify(['server/src/test/readiness.ts']),
+  });
+
+  assert.match(text, /Server readiness race causes ECONNREFUSED/);
+  assert.match(text, /Requests must wait for server readiness/);
+  assert.match(text, /Await readiness before issuing HTTP requests/);
+  assert.match(text, /Visible key conclusions stay searchable/);
+  assert.match(text, /readiness testing/);
+  assert.match(text, /Readiness helper wraps Fastify startup/);
+  assert.match(text, /Root cause: Client calls raced server startup\./);
+  assert.match(text, /Resolution: Block request setup until server readiness resolves\./);
+  assert.match(text, /Pitfall: Do not fire API requests before Fastify ready\./);
+  assert.match(text, /Pattern: Share a readiness helper across HTTP tests\./);
+  assert.match(text, /Decision: Keep readiness helper in test utilities\./);
+  assert.match(text, /Error signature: ECONNREFUSED 127\.0\.0\.1:3721/);
+  assert.match(text, /File: server\/src\/test\/readiness\.ts/);
+});
+
+test('buildNoteEmbeddingText includes bounded code snippet bodies for memory notes', () => {
+  const longBody = 'x'.repeat(1005);
+  const text = buildNoteEmbeddingText({
+    title: 'Readiness helper memory',
+    summary: 'Code evidence should match the validation preview.',
+    keyConclusionsJson: '[]',
+    codeSnippetsJson: JSON.stringify([
+      {
+        language: 'ts',
+        code: "await fastify.ready();\nawait client.get('/api/status');",
+      },
+      {
+        code: longBody,
+      },
+    ]),
+    tagsText: null,
+    sourceType: 'agent-writeback',
+    rawPayloadJson: '{}',
+    errorSignaturesJson: '[]',
+    filesTouchedJson: '[]',
+  });
+
+  assert.match(
+    text,
+    /Code snippet \(ts\): await fastify\.ready\(\); await client\.get\('\/api\/status'\);/,
+  );
+  assert.match(text, new RegExp(`Code snippet \\(text\\): ${'x'.repeat(1000)}(?!x)`));
+});
+
+test('buildNoteEmbeddingText ignores malformed JSON defensively', () => {
+  assert.doesNotThrow(() => {
+    buildNoteEmbeddingText({
+      title: 'Malformed memory payload',
+      summary: 'Embedding text still includes stable fields.',
+      keyConclusionsJson: '{not-json',
+      codeSnippetsJson: 'also-not-json',
+      tagsText: null,
+      sourceType: 'agent-writeback',
+      rawPayloadJson: '{"root_cause"',
+      errorSignaturesJson: '[broken',
+      filesTouchedJson: '{broken',
+    });
+  });
+});
+
+test('buildNoteEmbeddingText skips raw memory payload details for imported conversations', () => {
+  const text = buildNoteEmbeddingText({
+    title: 'Imported conversation note',
+    summary: 'Imported summaries still embed visible note fields.',
+    keyConclusionsJson: JSON.stringify(['Visible imported conclusion.']),
+    codeSnippetsJson: '[]',
+    tagsText: null,
+    sourceType: 'imported-conversation',
+    rawPayloadJson: JSON.stringify({
+      root_cause: 'SHOULD_NOT_EMBED_ROOT_CAUSE',
+      reusable_patterns: ['SHOULD_NOT_EMBED_PATTERN'],
+      decisions: ['SHOULD_NOT_EMBED_DECISION'],
+    }),
+    errorSignaturesJson: JSON.stringify(['SHOULD_NOT_EMBED_SIGNATURE']),
+    filesTouchedJson: JSON.stringify(['SHOULD_NOT_EMBED_FILE']),
+  });
+
+  assert.match(text, /Imported conversation note/);
+  assert.match(text, /Visible imported conclusion/);
+  assert.equal(text.includes('SHOULD_NOT_EMBED_ROOT_CAUSE'), false);
+  assert.equal(text.includes('SHOULD_NOT_EMBED_PATTERN'), false);
+  assert.equal(text.includes('SHOULD_NOT_EMBED_DECISION'), false);
+  assert.equal(text.includes('SHOULD_NOT_EMBED_SIGNATURE'), false);
+  assert.equal(text.includes('SHOULD_NOT_EMBED_FILE'), false);
+});
+
 test('committed vectra ids come from persisted index state, not staged updates', async () => {
   const dir = createTempDir();
   const index = new LocalIndex(join(dir, 'vectra-index'));