feat(memory): project-scoped memory writes and .qwen/QWEN.local.md

packages/acp-bridge/src/status.ts

@@ -307,15 +307,17 @@ export interface ServeSessionSupportedCommandsStatus {
  * so the SDK reducer can render any of these with one pattern.
  */
 
-export type ServeContextFileScope = 'workspace' | 'global';
+export type ServeContextFileScope = 'workspace' | 'local' | 'global';
 
 export interface ServeWorkspaceMemoryFile {
   kind: 'memory_file';
   /** Absolute path to the discovered memory file. */
   path: string;
   /**
-   * 'workspace' for files under the bound workspace tree, 'global' for
-   * `~/.qwen/QWEN.md` style entries. Helps adapters render scope chips.
+   * 'workspace' for files under the bound workspace tree, 'local' for
+   * `.qwen/QWEN.local.md` (gitignored project-local instructions),
+   * 'global' for `~/.qwen/QWEN.md` style entries.
+   * Helps adapters render scope chips.
    */
   scope: ServeContextFileScope;
   /** Size in bytes of the file's serialized contents on disk. */

packages/cli/src/serve/workspaceMemory.ts

@@ -12,7 +12,10 @@ import {
   WorkspaceMemoryFileTooLargeError,
   WorkspaceMemoryWriteTimeoutError,
   getAllGeminiMdFilenames,
+  LOCAL_CONTEXT_FILENAME,
+  QWEN_DIR,
   writeWorkspaceContextFile,
+  type WriteContextFileScope,
 } from '@qwen-code/qwen-code-core';
 import { writeStderrLine } from '../utils/stdioHelpers.js';
 import { isServeDebugMode } from './debugMode.js';
@@ -78,6 +81,13 @@ export interface WorkspaceMemoryRouteDeps {
 
 const MAX_MEMORY_CONTENT_BYTES = 1024 * 1024;
 
+const VALID_SCOPES: ReadonlySet<string> = new Set([
+  'workspace',
+  'global',
+  'local',
+  'auto',
+]);
+
 /** Mount the two memory routes on the supplied Express app. */
 export function mountWorkspaceMemoryRoutes(
   app: Application,
@@ -116,9 +126,9 @@ export function mountWorkspaceMemoryRoutes(
       const body = deps.safeBody(req);
 
       const scope = body['scope'];
-      if (scope !== 'workspace' && scope !== 'global') {
+      if (!VALID_SCOPES.has(scope as string)) {
         res.status(400).json({
-          error: '`scope` must be "workspace" or "global"',
+          error: `\`scope\` must be one of: ${[...VALID_SCOPES].map((s) => `"${s}"`).join(', ')}`,
           code: 'invalid_scope',
         });
         return;
@@ -183,7 +193,7 @@ export function mountWorkspaceMemoryRoutes(
 
       try {
         const result = await writeWorkspaceContextFile({
-          scope,
+          scope: scope as WriteContextFileScope,
           mode,
           content,
           projectRoot: deps.boundWorkspace,
@@ -337,6 +347,29 @@ async function collectWorkspaceMemoryStatus(
   );
   files.push(...workspaceFiles);
 
+  // Probe for .qwen/QWEN.local.md at the workspace root.
+  const localPath = path.join(boundWorkspace, QWEN_DIR, LOCAL_CONTEXT_FILENAME);
+  try {
+    const stat = await fs.stat(localPath);
+    if (stat.isFile()) {
+      files.push({
+        absolutePath: localPath,
+        scope: 'local',
+        bytes: stat.size,
+      });
+    }
+  } catch (err) {
+    if (!isEnoent(err)) {
+      errors.push({
+        kind: 'memory_file',
+        status: 'error',
+        error: err instanceof Error ? err.message : String(err),
+        errorKind: 'stat_failed',
+        hint: localPath,
+      });
+    }
+  }
+
   const globalDir = Storage.getGlobalQwenDir();
   for (const filename of filenames) {
     const candidate = path.join(globalDir, filename);

packages/core/src/memory/const.ts

@@ -6,6 +6,7 @@
 
 export const DEFAULT_CONTEXT_FILENAME = 'QWEN.md';
 export const AGENT_CONTEXT_FILENAME = 'AGENTS.md';
+export const LOCAL_CONTEXT_FILENAME = 'QWEN.local.md';
 export const MEMORY_SECTION_HEADER = '## Qwen Added Memories';
 
 // This variable will hold the currently configured filename for context files.

packages/core/src/memory/writeContextFile.test.ts

@@ -9,9 +9,11 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Storage } from '../config/storage.js';
+import { QWEN_DIR } from '../utils/paths.js';
 import {
   AGENT_CONTEXT_FILENAME,
   DEFAULT_CONTEXT_FILENAME,
+  LOCAL_CONTEXT_FILENAME,
   MEMORY_SECTION_HEADER,
   setGeminiMdFilename,
 } from './const.js';
@@ -391,4 +393,206 @@ describe('writeWorkspaceContextFile', () => {
       setGeminiMdFilename(DEFAULT_CONTEXT_FILENAME);
     }
   });
+
+  describe('auto scope', () => {
+    let savedFilenames: string | string[];
+
+    beforeEach(() => {
+      // Capture whatever the filename list is before we touch it.
+      savedFilenames = [DEFAULT_CONTEXT_FILENAME, AGENT_CONTEXT_FILENAME];
+      setGeminiMdFilename(savedFilenames);
+    });
+
+    afterEach(() => {
+      setGeminiMdFilename(savedFilenames);
+    });
+
+    it('writes to project QWEN.md when one exists at the project root', async () => {
+      const projectQwenPath = path.join(workspace, DEFAULT_CONTEXT_FILENAME);
+      await fs.writeFile(projectQwenPath, '# project\n', 'utf8');
+
+      const result = await writeWorkspaceContextFile({
+        scope: 'auto',
+        mode: 'append',
+        content: '- memory entry',
+        projectRoot: workspace,
+      });
+
+      expect(result.filePath).toBe(projectQwenPath);
+      const written = await fs.readFile(projectQwenPath, 'utf8');
+      expect(written).toContain('- memory entry');
+      // Global dir must not have been touched.
+      const globalPath = path.join(globalDir, DEFAULT_CONTEXT_FILENAME);
+      await expect(fs.access(globalPath)).rejects.toMatchObject({
+        code: 'ENOENT',
+      });
+    });
+
+    it('writes to project AGENTS.md when that exists instead of QWEN.md', async () => {
+      const agentsPath = path.join(workspace, AGENT_CONTEXT_FILENAME);
+      await fs.writeFile(agentsPath, '# agents\n', 'utf8');
+
+      const result = await writeWorkspaceContextFile({
+        scope: 'auto',
+        mode: 'append',
+        content: '- agents memory',
+        projectRoot: workspace,
+      });
+
+      expect(result.filePath).toBe(agentsPath);
+      const written = await fs.readFile(agentsPath, 'utf8');
+      expect(written).toContain('- agents memory');
+      // QWEN.md must not be created.
+      await expect(
+        fs.access(path.join(workspace, DEFAULT_CONTEXT_FILENAME)),
+      ).rejects.toMatchObject({ code: 'ENOENT' });
+    });
+
+    it('falls back to global when no project context file exists', async () => {
+      const result = await writeWorkspaceContextFile({
+        scope: 'auto',
+        mode: 'append',
+        content: '- fallback entry',
+        projectRoot: workspace,
+      });
+
+      expect(result.filePath).toBe(
+        path.join(globalDir, DEFAULT_CONTEXT_FILENAME),
+      );
+      expect(getGlobalQwenDirSpy).toHaveBeenCalled();
+      const written = await fs.readFile(result.filePath, 'utf8');
+      expect(written).toBe(MEMORY_SECTION_HEADER + '\n- fallback entry\n');
+    });
+
+    it('prefers QWEN.md over AGENTS.md when both exist (QWEN.md first in filenames list)', async () => {
+      const qwenPath = path.join(workspace, DEFAULT_CONTEXT_FILENAME);
+      const agentsPath = path.join(workspace, AGENT_CONTEXT_FILENAME);
+      await fs.writeFile(qwenPath, '# qwen\n', 'utf8');
+      await fs.writeFile(agentsPath, '# agents\n', 'utf8');
+
+      const result = await writeWorkspaceContextFile({
+        scope: 'auto',
+        mode: 'append',
+        content: '- which one?',
+        projectRoot: workspace,
+      });
+
+      // Should prefer QWEN.md since getAllGeminiMdFilenames returns it first.
+      expect(result.filePath).toBe(qwenPath);
+      const qwenContent = await fs.readFile(qwenPath, 'utf8');
+      expect(qwenContent).toContain('- which one?');
+    });
+
+    it('falls back to local file when no committed context exists', async () => {
+      const localPath = path.join(workspace, QWEN_DIR, LOCAL_CONTEXT_FILENAME);
+      await fs.mkdir(path.dirname(localPath), { recursive: true });
+      await fs.writeFile(localPath, '# local\n', 'utf8');
+
+      const result = await writeWorkspaceContextFile({
+        scope: 'auto',
+        mode: 'append',
+        content: '- auto local entry',
+        projectRoot: workspace,
+      });
+
+      expect(result.filePath).toBe(localPath);
+      const written = await fs.readFile(localPath, 'utf8');
+      expect(written).toContain('- auto local entry');
+    });
+
+    it('prefers committed QWEN.md over local file in auto scope', async () => {
+      const qwenPath = path.join(workspace, DEFAULT_CONTEXT_FILENAME);
+      const localPath = path.join(workspace, QWEN_DIR, LOCAL_CONTEXT_FILENAME);
+      await fs.writeFile(qwenPath, '# qwen\n', 'utf8');
+      await fs.mkdir(path.dirname(localPath), { recursive: true });
+      await fs.writeFile(localPath, '# local\n', 'utf8');
+
+      const result = await writeWorkspaceContextFile({
+        scope: 'auto',
+        mode: 'append',
+        content: '- which scope?',
+        projectRoot: workspace,
+      });
+
+      expect(result.filePath).toBe(qwenPath);
+    });
+  });
+
+  describe('local scope', () => {
+    it('writes to .qwen/QWEN.local.md', async () => {
+      const result = await writeWorkspaceContextFile({
+        scope: 'local',
+        mode: 'append',
+        content: '- local entry',
+        projectRoot: workspace,
+      });
+
+      const expectedPath = path.join(
+        workspace,
+        QWEN_DIR,
+        LOCAL_CONTEXT_FILENAME,
+      );
+      expect(result.filePath).toBe(expectedPath);
+      const written = await fs.readFile(expectedPath, 'utf8');
+      expect(written).toBe(`${MEMORY_SECTION_HEADER}\n- local entry\n`);
+    });
+
+    it('creates the .qwen directory if missing', async () => {
+      const qwenDir = path.join(workspace, QWEN_DIR);
+      await expect(fs.access(qwenDir)).rejects.toMatchObject({
+        code: 'ENOENT',
+      });
+
+      await writeWorkspaceContextFile({
+        scope: 'local',
+        mode: 'append',
+        content: '- created',
+        projectRoot: workspace,
+      });
+
+      const stat = await fs.stat(qwenDir);
+      expect(stat.isDirectory()).toBe(true);
+    });
+
+    it('adds .qwen/QWEN.local.md to .gitignore on first write', async () => {
+      await writeWorkspaceContextFile({
+        scope: 'local',
+        mode: 'append',
+        content: '- local entry',
+        projectRoot: workspace,
+      });
+
+      const gitignore = await fs.readFile(
+        path.join(workspace, '.gitignore'),
+        'utf8',
+      );
+      expect(gitignore).toContain(`${QWEN_DIR}/${LOCAL_CONTEXT_FILENAME}`);
+    });
+
+    it('does not duplicate the gitignore entry on subsequent writes', async () => {
+      await writeWorkspaceContextFile({
+        scope: 'local',
+        mode: 'append',
+        content: '- first',
+        projectRoot: workspace,
+      });
+      await writeWorkspaceContextFile({
+        scope: 'local',
+        mode: 'append',
+        content: '- second',
+        projectRoot: workspace,
+      });
+
+      const gitignore = await fs.readFile(
+        path.join(workspace, '.gitignore'),
+        'utf8',
+      );
+      const count = gitignore
+        .split('\n')
+        .filter(
+          (l) => l.trim() === `${QWEN_DIR}/${LOCAL_CONTEXT_FILENAME}`,
+        ).length;
+      expect(count).toBe(1);
+    });
+  });
 });