@vuau/agent-memory 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @vuau/agent-memory
 
-Structured AI memory for codebases. Works with GitHub Copilot, Cursor, Windsurf, VS Code, OpenCode, and [25+ other AI coding tools](#supported-tools).
+Structured AI memory for codebases. Uses `AGENTS.md` to work with OpenCode, GitHub Copilot, Cursor, Windsurf, and any AI coding assistant that reads markdown files.
 
 **[Tiếng Việt →](./README.vi.md)**
 
@@ -19,28 +19,26 @@ AI coding assistants lose context between sessions. They can't remember:
 npx @vuau/agent-memory init
 ```
 
-That's it. Creates `AGENTS.md` + `.agents/` structure.
-
 ## What It Creates
 
 ```
 / (Project Root)
-├── AGENTS.md           # Universal agent instructions
+├── AGENTS.md                    # Root agent rules
 └── .agents/
-    ├── MEMORY.md       # Long-term memory (decisions, patterns)
-    ├── TASKS.md        # Working memory (current tasks)
-    └── spec/           # Detailed specs (on-demand)
+    ├── MEMORY.md                # Long-term memory (decisions, patterns)
+    ├── TASKS.md                 # Working memory (current tasks)
+    └── spec/                    # Detailed specs (on-demand)
 ```
 
 ## How It Works
 
 1. **You run `init`** → Creates `AGENTS.md` + `.agents/` structure
-2. **Agent reads AGENTS.md** → Finds documentation map pointing to `.agents/`
+2. **Agent reads rules** → Finds documentation map pointing to `.agents/`
 3. **Agent works** → Reads MEMORY.md before implementing, updates TASKS.md
 4. **You approve decision** → Agent writes 1-line entry to MEMORY.md
 5. **Next session** → Agent reads memory, continues where you left off
 
-**No plugin required.** The instructions in AGENTS.md tell the agent what to do.
+**No plugin required.** The rules in `AGENTS.md` instruct the agent what to do.
 
 ## CLI Options
 
@@ -48,8 +46,8 @@ That's it. Creates `AGENTS.md` + `.agents/` structure.
 npx @vuau/agent-memory init [options]
 
 Options:
-  --force        Overwrite existing files without asking
-  --name <n>     Project name (default: from package.json)
+  --force       Overwrite existing files without asking
+  --name <n>    Project name (default: from package.json)
 
 npx @vuau/agent-memory doctor   # Validate structure
 npx @vuau/agent-memory help     # Show help
@@ -57,7 +55,7 @@ npx @vuau/agent-memory help     # Show help
 
 ## Memory Protocol
 
-Agents follow this protocol (defined in AGENTS.md):
+Agents follow this protocol (defined in config files):
 
 ```markdown
 ## When to write
@@ -82,11 +80,11 @@ Agents follow this protocol (defined in AGENTS.md):
 
 ## Architecture
 
-### 3-Layer Design
+### 4-Layer Design
 
 | Layer | File | Purpose |
 |-------|------|---------|
-| Instructions | AGENTS.md | Rules + pointers (~100 lines) |
+| Router | AGENTS.md | Rules + pointers (~100 lines) |
 | Memory | .agents/MEMORY.md | Curated decisions (1-line each) |
 | Tasks | .agents/TASKS.md | Current work, next steps |
 | Specs | .agents/spec/*.md | Detailed docs (on-demand) |
@@ -104,17 +102,21 @@ File-based solution:
 - Plain markdown (portable, git-versionable, human-readable)
 - No dependencies (works everywhere)
 
-## Supported Tools
+## Cross-IDE Compatibility
+
+By default, we only scaffold `AGENTS.md`, which is an emerging standard router file.
 
-AGENTS.md is the universal format, supported by **25+ AI coding tools**:
+If your tool requires a specific file (e.g. Cursor requires `.cursorrules`, GitHub Copilot requires `.github/copilot-instructions.md`), you can simply symlink or copy `AGENTS.md`:
 
-| Category | Tools |
-|----------|-------|
-| **IDEs** | Cursor, Windsurf, VS Code, Zed, RooCode, Kilo Code |
-| **CLI Tools** | OpenCode, Aider, goose, Gemini CLI, Warp, Augment Code |
-| **AI Agents** | GitHub Copilot, Codex (OpenAI), Jules (Google), Junie (JetBrains), Devin, Factory, Amp, Phoenix, Semgrep, Ona, UiPath Autopilot |
+```bash
+# For Cursor
+ln -s AGENTS.md .cursorrules
+
+# For GitHub Copilot
+mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
+```
 
-See [agents.md](https://agents.md) for the full list.
+All tools will read from the same underlying `.agents/` memory structure.
 
 ## Documentation
 

package/README.vi.md

@@ -1,6 +1,6 @@
 # @vuau/agent-memory
 
-Bộ nhớ AI có cấu trúc cho các codebase. Hoạt động với GitHub Copilot, Cursor, Windsurf, VS Code, OpenCode, và [25+ AI coding tools khác](#supported-tools).
+Bộ nhớ AI có cấu trúc cho các codebase. Sử dụng `AGENTS.md` để hoạt động với OpenCode, GitHub Copilot, Cursor, Windsurf, và bất kỳ AI coding assistant nào đọc markdown files.
 
 ## Bài toán
 
@@ -17,28 +17,26 @@ AI coding assistants mất bối cảnh giữa các phiên. Họ không thể nh
 npx @vuau/agent-memory init
 ```
 
-Đơn giản vậy thôi. Tạo `AGENTS.md` + `.agents/` structure.
-
 ## Cấu trúc tạo ra
 
 ```
 / (Project Root)
-├── AGENTS.md           # Universal agent instructions
+├── AGENTS.md                    # Root agent rules
 └── .agents/
-    ├── MEMORY.md       # Long-term memory (decisions, patterns)
-    ├── TASKS.md        # Working memory (current tasks)
-    └── spec/           # Detailed specs (on-demand)
+    ├── MEMORY.md                # Long-term memory (decisions, patterns)
+    ├── TASKS.md                 # Working memory (current tasks)
+    └── spec/                    # Detailed specs (on-demand)
 ```
 
 ## Cách hoạt động
 
 1. **Bạn chạy `init`** → Tạo `AGENTS.md` + `.agents/` structure
-2. **Agent đọc AGENTS.md** → Tìm documentation map trỏ đến `.agents/`
+2. **Agent đọc rules** → Tìm documentation map trỏ đến `.agents/`
 3. **Agent làm việc** → Đọc MEMORY.md trước khi implement, update TASKS.md
 4. **Bạn approve decision** → Agent ghi 1-line entry vào MEMORY.md
 5. **Phiên tiếp theo** → Agent đọc memory, tiếp tục từ nơi dừng lại
 
-**Không cần plugin.** Instructions trong AGENTS.md hướng dẫn agent phải làm gì.
+**Không cần plugin.** Rules trong `AGENTS.md` hướng dẫn agent phải làm gì.
 
 ## CLI Options
 
@@ -46,8 +44,8 @@ npx @vuau/agent-memory init
 npx @vuau/agent-memory init [options]
 
 Options:
-  --force        Ghi đè files có sẵn mà không hỏi
-  --name <n>     Tên project (mặc định: từ package.json)
+  --force       Ghi đè files có sẵn mà không hỏi
+  --name <n>    Tên project (mặc định: từ package.json)
 
 npx @vuau/agent-memory doctor   # Validate structure
 npx @vuau/agent-memory help     # Hiện help
@@ -55,7 +53,7 @@ npx @vuau/agent-memory help     # Hiện help
 
 ## Memory Protocol
 
-Agents follow protocol này (defined trong AGENTS.md):
+Agents follow protocol này (defined trong config files):
 
 ```markdown
 ## Khi nào ghi
@@ -80,11 +78,11 @@ Agents follow protocol này (defined trong AGENTS.md):
 
 ## Kiến trúc
 
-### Thiết kế 3-Layer
+### Thiết kế 4-Layer
 
 | Layer | File | Mục đích |
 |-------|------|----------|
-| Instructions | AGENTS.md | Rules + pointers (~100 dòng) |
+| Router | AGENTS.md | Rules + pointers (~100 dòng) |
 | Memory | .agents/MEMORY.md | Curated decisions (1-line each) |
 | Tasks | .agents/TASKS.md | Current work, next steps |
 | Specs | .agents/spec/*.md | Detailed docs (on-demand) |
@@ -102,17 +100,21 @@ File-based solution:
 - Plain markdown (portable, git-versionable, human-readable)
 - Không dependencies (works everywhere)
 
-## Supported Tools
+## Cross-IDE Compatibility
+
+Mặc định, công cụ chỉ scaffold `AGENTS.md`, một chuẩn router file đang phổ biến.
 
-AGENTS.md là format universal, được hỗ trợ bởi **25+ AI coding tools**:
+Nếu công cụ của bạn yêu cầu một file cụ thể (vd: Cursor yêu cầu `.cursorrules`, GitHub Copilot yêu cầu `.github/copilot-instructions.md`), bạn có thể đơn giản dùng symlink hoặc copy `AGENTS.md`:
 
-| Category | Tools |
-|----------|-------|
-| **IDEs** | Cursor, Windsurf, VS Code, Zed, RooCode, Kilo Code |
-| **CLI Tools** | OpenCode, Aider, goose, Gemini CLI, Warp, Augment Code |
-| **AI Agents** | GitHub Copilot, Codex (OpenAI), Jules (Google), Junie (JetBrains), Devin, Factory, Amp, Phoenix, Semgrep, Ona, UiPath Autopilot |
+```bash
+# Cho Cursor
+ln -s AGENTS.md .cursorrules
+
+# Cho GitHub Copilot
+mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
+```
 
-Xem [agents.md](https://agents.md) để có danh sách đầy đủ.
+Tất cả các công cụ sẽ cùng đọc chung cấu trúc bộ nhớ bên trong thư mục `.agents/`.
 
 ## Tài liệu
 

package/dist/bin/cli.js

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
 
 // bin/cli.ts
-import * as readline from "readline";
 import { existsSync as existsSync3 } from "fs";
 import { join as join3 } from "path";
 
-// src/core/scaffold.ts
+// src/scaffold.ts
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
 import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 
-// src/core/types.ts
+// src/types.ts
 var AGENTS_DIR = ".agents";
 var SPEC_DIR = ".agents/spec";
 var MEMORY_FILE = ".agents/MEMORY.md";
 var MEMORY_DETAIL_FILE = ".agents/MEMORY-DETAIL.md";
 var TASKS_FILE = ".agents/TASKS.md";
+var CUSTOM_FILE = ".agents/CUSTOM.md";
 var AGENTS_MD = "AGENTS.md";
 
-// src/core/scaffold.ts
+// src/scaffold.ts
 function getTemplatesDir() {
   const thisDir = dirname(fileURLToPath(import.meta.url));
   const fromSource = resolve(thisDir, "../../templates");
@@ -56,17 +56,11 @@ function scaffold(projectDir, options = {}) {
       mkdirSync(dir, { recursive: true });
     }
   }
-  writeFileIfNeeded(
-    join(projectDir, AGENTS_MD),
-    applyVars(readTemplate("AGENTS.md"), vars),
-    AGENTS_MD,
-    result,
-    force
-  );
   const coreFiles = [
     { target: MEMORY_FILE, template: "MEMORY.md" },
     { target: MEMORY_DETAIL_FILE, template: "MEMORY-DETAIL.md" },
-    { target: TASKS_FILE, template: "TASKS.md" }
+    { target: TASKS_FILE, template: "TASKS.md" },
+    { target: CUSTOM_FILE, template: "CUSTOM.md" }
   ];
   for (const { target, template } of coreFiles) {
     const targetPath = join(projectDir, target);
@@ -83,6 +77,13 @@ function scaffold(projectDir, options = {}) {
     writeFileSync(specKeep, "");
     result.created.push(`${SPEC_DIR}/.gitkeep`);
   }
+  writeFileIfNeeded(
+    join(projectDir, AGENTS_MD),
+    applyVars(readTemplate("AGENTS.md"), vars),
+    AGENTS_MD,
+    result,
+    force
+  );
   return result;
 }
 function writeFileIfNeeded(targetPath, content, displayName, result, force) {
@@ -104,14 +105,24 @@ function guessProjectName(dir) {
   }
   return dir.split("/").pop() || "Project";
 }
+function updateRouter(projectDir) {
+  const targetPath = join(projectDir, AGENTS_MD);
+  if (!existsSync(targetPath)) return false;
+  const projectName = guessProjectName(projectDir);
+  const vars = { PROJECT_NAME: projectName };
+  const content = applyVars(readTemplate("AGENTS.md"), vars);
+  writeFileSync(targetPath, content);
+  return true;
+}
 
-// src/core/doctor.ts
+// src/doctor.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
 function doctor(projectDir) {
   const issues = [];
   const required = [
-    { file: AGENTS_MD, desc: "Root agent instructions" },
+    { file: AGENTS_MD, desc: "Root router file" },
+    { file: CUSTOM_FILE, desc: "Project specific rules" },
     { file: MEMORY_FILE, desc: "Long-term memory" },
     { file: TASKS_FILE, desc: "Working memory" }
   ];
@@ -140,7 +151,7 @@ function doctor(projectDir) {
       issues.push({
         level: "warning",
         file: AGENTS_MD,
-        message: "Over 150 lines \u2014 consider keeping it concise"
+        message: "Over 150 lines \u2014 consider keeping it concise as a router"
       });
     }
   }
@@ -161,28 +172,13 @@ function doctor(projectDir) {
 // bin/cli.ts
 var args = process.argv.slice(2);
 var command = args[0];
-var rl = readline.createInterface({
-  input: process.stdin,
-  output: process.stdout
-});
-function ask(question) {
-  return new Promise((resolve2) => {
-    rl.question(question, (answer) => resolve2(answer.trim()));
-  });
-}
-function askYesNo(question, defaultYes = true) {
-  const hint = defaultYes ? "(Y/n)" : "(y/N)";
-  return ask(`${question} ${hint} `).then((answer) => {
-    if (!answer) return defaultYes;
-    return answer.toLowerCase().startsWith("y");
-  });
-}
 function printUsage() {
   console.log(`
 @vuau/agent-memory \u2014 Structured AI memory for codebases
 
 Usage:
-  agent-memory init [options]    Scaffold AGENTS.md + .agents/ structure
+  agent-memory init [options]    Scaffold .agents/ structure and AGENTS.md
+  agent-memory update            Update AGENTS.md router to latest version
   agent-memory doctor            Validate .agents/ structure
   agent-memory help              Show this help
 
@@ -191,14 +187,8 @@ Options (init):
   --name <name>                  Project name (default: from package.json)
 
 Examples:
-  npx @vuau/agent-memory init              # Create AGENTS.md + .agents/
-  npx @vuau/agent-memory init --force      # Overwrite existing files
-  npx @vuau/agent-memory doctor            # Check structure
-
-AGENTS.md is the universal format supported by 25+ AI coding tools:
-  GitHub Copilot, Cursor, Windsurf, VS Code, OpenCode, Codex, Jules,
-  Junie, Gemini CLI, Devin, Aider, goose, Factory, Amp, RooCode,
-  Zed, Warp, Kilo Code, Phoenix, Semgrep, Ona, UiPath, Augment Code...
+  npx @vuau/agent-memory init
+  npx @vuau/agent-memory init --force
 `);
 }
 async function runInit() {
@@ -207,31 +197,9 @@ async function runInit() {
   const nameIdx = args.indexOf("--name");
   const projectName = nameIdx !== -1 ? args[nameIdx + 1] : void 0;
   const options = {
-    projectName
+    projectName,
+    force
   };
-  if (!force) {
-    const filesToCheck = [
-      { path: AGENTS_MD, name: "AGENTS.md" },
-      { path: MEMORY_FILE, name: ".agents/MEMORY.md" },
-      { path: TASKS_FILE, name: ".agents/TASKS.md" }
-    ];
-    const existingFiles = filesToCheck.filter((f) => existsSync3(join3(cwd, f.path)));
-    if (existingFiles.length > 0) {
-      console.log("\nExisting files found:");
-      for (const f of existingFiles) {
-        console.log(`  - ${f.name}`);
-      }
-      const overwrite = await askYesNo("\nOverwrite these files?", false);
-      if (!overwrite) {
-        console.log("\nAborted. Use --force to overwrite without asking.\n");
-        rl.close();
-        return;
-      }
-      options.force = true;
-    }
-  } else {
-    options.force = true;
-  }
   console.log(`
 Initializing agent memory in ${cwd}...
 `);
@@ -247,13 +215,35 @@ Initializing agent memory in ${cwd}...
     for (const f of result.skipped) {
       console.log(`  - ${f}`);
     }
+    if (!force) {
+      console.log("\nTip: Use --force to overwrite existing files.");
+    }
   }
   console.log("\nNext steps:");
   console.log("  1. Edit AGENTS.md \u2014 add project-specific rules");
   console.log("  2. Add spec files to .agents/spec/ for detailed documentation");
-  console.log("  3. AI agents will read AGENTS.md and write to .agents/ automatically");
+  console.log("  3. Agent will read rules and write to .agents/MEMORY.md automatically");
+  console.log("");
+}
+async function runUpdate() {
+  const cwd = process.cwd();
+  const agentsMdPath = join3(cwd, AGENTS_MD);
+  if (!existsSync3(agentsMdPath)) {
+    console.error("\u2717 AGENTS.md not found. Please run 'agent-memory init' first.");
+    process.exit(1);
+  }
+  console.log(`
+Updating ${AGENTS_MD} in ${cwd}...
+`);
+  const updated = updateRouter(cwd);
+  if (updated) {
+    console.log(`  \u2713 ${AGENTS_MD} updated to the latest template.`);
+    console.log(`  (Note: Your custom rules in .agents/CUSTOM.md were not affected)`);
+  } else {
+    console.error("\u2717 Failed to update AGENTS.md");
+    process.exit(1);
+  }
   console.log("");
-  rl.close();
 }
 function runDoctor() {
   const cwd = process.cwd();
@@ -278,7 +268,12 @@ switch (command) {
   case "init":
     runInit().catch((err) => {
       console.error("Error:", err.message);
-      rl.close();
+      process.exit(1);
+    });
+    break;
+  case "update":
+    runUpdate().catch((err) => {
+      console.error("Error:", err.message);
       process.exit(1);
     });
     break;
@@ -293,7 +288,6 @@ switch (command) {
   case void 0:
     runInit().catch((err) => {
       console.error("Error:", err.message);
-      rl.close();
       process.exit(1);
     });
     break;

package/dist/index.js

@@ -1,17 +1,18 @@
-// src/core/scaffold.ts
+// src/scaffold.ts
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
 import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
 
-// src/core/types.ts
+// src/types.ts
 var AGENTS_DIR = ".agents";
 var SPEC_DIR = ".agents/spec";
 var MEMORY_FILE = ".agents/MEMORY.md";
 var MEMORY_DETAIL_FILE = ".agents/MEMORY-DETAIL.md";
 var TASKS_FILE = ".agents/TASKS.md";
+var CUSTOM_FILE = ".agents/CUSTOM.md";
 var AGENTS_MD = "AGENTS.md";
 
-// src/core/scaffold.ts
+// src/scaffold.ts
 function getTemplatesDir() {
   const thisDir = dirname(fileURLToPath(import.meta.url));
   const fromSource = resolve(thisDir, "../../templates");
@@ -49,17 +50,11 @@ function scaffold(projectDir, options = {}) {
       mkdirSync(dir, { recursive: true });
     }
   }
-  writeFileIfNeeded(
-    join(projectDir, AGENTS_MD),
-    applyVars(readTemplate("AGENTS.md"), vars),
-    AGENTS_MD,
-    result,
-    force
-  );
   const coreFiles = [
     { target: MEMORY_FILE, template: "MEMORY.md" },
     { target: MEMORY_DETAIL_FILE, template: "MEMORY-DETAIL.md" },
-    { target: TASKS_FILE, template: "TASKS.md" }
+    { target: TASKS_FILE, template: "TASKS.md" },
+    { target: CUSTOM_FILE, template: "CUSTOM.md" }
   ];
   for (const { target, template } of coreFiles) {
     const targetPath = join(projectDir, target);
@@ -76,6 +71,13 @@ function scaffold(projectDir, options = {}) {
     writeFileSync(specKeep, "");
     result.created.push(`${SPEC_DIR}/.gitkeep`);
   }
+  writeFileIfNeeded(
+    join(projectDir, AGENTS_MD),
+    applyVars(readTemplate("AGENTS.md"), vars),
+    AGENTS_MD,
+    result,
+    force
+  );
   return result;
 }
 function writeFileIfNeeded(targetPath, content, displayName, result, force) {
@@ -97,134 +99,41 @@ function guessProjectName(dir) {
   }
   return dir.split("/").pop() || "Project";
 }
-
-// src/core/memory.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join2 } from "path";
-function appendMemory(projectDir, entry) {
-  const filePath = join2(projectDir, MEMORY_FILE);
-  if (!existsSync2(filePath)) {
-    throw new Error(`${MEMORY_FILE} not found. Run 'agent-memory init' first.`);
-  }
-  const content = readFileSync2(filePath, "utf-8");
-  const category = entry.category || "Decisions";
-  const line = `- ${entry.date}: ${entry.content}`;
-  const categoryHeader = `## ${category}`;
-  const headerIndex = content.indexOf(categoryHeader);
-  let updated;
-  if (headerIndex === -1) {
-    updated = content.trimEnd() + `
-
-${categoryHeader}
-${line}
-`;
-  } else {
-    const afterHeader = headerIndex + categoryHeader.length;
-    const nextHeaderIndex = content.indexOf("\n## ", afterHeader);
-    const insertAt = nextHeaderIndex === -1 ? content.length : nextHeaderIndex;
-    const categoryContent = content.slice(afterHeader, insertAt);
-    const lastLineEnd = afterHeader + categoryContent.trimEnd().length;
-    updated = content.slice(0, lastLineEnd) + "\n" + line + content.slice(lastLineEnd);
-  }
-  writeFileSync2(filePath, updated);
-}
-function readMemory(projectDir) {
-  const filePath = join2(projectDir, MEMORY_FILE);
-  if (!existsSync2(filePath)) return {};
-  const content = readFileSync2(filePath, "utf-8");
-  const categories = {};
-  let currentCategory = "_uncategorized";
-  for (const line of content.split("\n")) {
-    const headerMatch = line.match(/^## (.+)/);
-    if (headerMatch) {
-      currentCategory = headerMatch[1];
-      categories[currentCategory] = categories[currentCategory] || [];
-      continue;
-    }
-    if (line.startsWith("- ") && currentCategory) {
-      categories[currentCategory] = categories[currentCategory] || [];
-      categories[currentCategory].push(line.slice(2));
-    }
-  }
-  return categories;
-}
-
-// src/core/tasks.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
-import { join as join3 } from "path";
-function readTasks(projectDir) {
-  const filePath = join3(projectDir, TASKS_FILE);
-  const result = {
-    in_progress: [],
-    up_next: [],
-    completed: []
-  };
-  if (!existsSync3(filePath)) return result;
-  const content = readFileSync3(filePath, "utf-8");
-  let currentSection = null;
-  for (const line of content.split("\n")) {
-    if (line.startsWith("## In Progress")) {
-      currentSection = "in_progress";
-      continue;
-    }
-    if (line.startsWith("## Up Next")) {
-      currentSection = "up_next";
-      continue;
-    }
-    if (line.startsWith("## Completed")) {
-      currentSection = "completed";
-      continue;
-    }
-    if (currentSection && line.startsWith("- ")) {
-      result[currentSection].push(line.slice(2));
-    }
-  }
-  return result;
-}
-function writeTasks(projectDir, tasks) {
-  const filePath = join3(projectDir, TASKS_FILE);
-  const content = `# Current Tasks
-
-Working memory for cross-session continuity. Update before ending a session.
-
----
-
-## In Progress
-${tasks.in_progress.map((t) => `- ${t}`).join("\n") || ""}
-
-## Up Next
-${tasks.up_next.map((t) => `- ${t}`).join("\n") || ""}
-
-## Completed
-${tasks.completed.map((t) => `- ${t}`).join("\n") || ""}
-`;
-  writeFileSync3(filePath, content);
+function updateRouter(projectDir) {
+  const targetPath = join(projectDir, AGENTS_MD);
+  if (!existsSync(targetPath)) return false;
+  const projectName = guessProjectName(projectDir);
+  const vars = { PROJECT_NAME: projectName };
+  const content = applyVars(readTemplate("AGENTS.md"), vars);
+  writeFileSync(targetPath, content);
+  return true;
 }
 
-// src/core/doctor.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
-import { join as join4 } from "path";
+// src/doctor.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
 function doctor(projectDir) {
   const issues = [];
   const required = [
-    { file: AGENTS_MD, desc: "Root agent instructions" },
+    { file: AGENTS_MD, desc: "Root router file" },
+    { file: CUSTOM_FILE, desc: "Project specific rules" },
     { file: MEMORY_FILE, desc: "Long-term memory" },
     { file: TASKS_FILE, desc: "Working memory" }
   ];
   for (const { file, desc } of required) {
-    const filePath = join4(projectDir, file);
-    if (!existsSync4(filePath)) {
+    const filePath = join2(projectDir, file);
+    if (!existsSync2(filePath)) {
       issues.push({ level: "error", file, message: `Missing ${desc}` });
     }
   }
   for (const dir of [AGENTS_DIR, SPEC_DIR]) {
-    if (!existsSync4(join4(projectDir, dir))) {
+    if (!existsSync2(join2(projectDir, dir))) {
       issues.push({ level: "error", file: dir, message: "Directory missing" });
     }
   }
-  const agentsPath = join4(projectDir, AGENTS_MD);
-  if (existsSync4(agentsPath)) {
-    const content = readFileSync4(agentsPath, "utf-8");
+  const agentsPath = join2(projectDir, AGENTS_MD);
+  if (existsSync2(agentsPath)) {
+    const content = readFileSync2(agentsPath, "utf-8");
     if (!content.includes(".agents/")) {
       issues.push({
         level: "warning",
@@ -236,13 +145,13 @@ function doctor(projectDir) {
       issues.push({
         level: "warning",
         file: AGENTS_MD,
-        message: "Over 150 lines \u2014 consider keeping it concise"
+        message: "Over 150 lines \u2014 consider keeping it concise as a router"
       });
     }
   }
-  const memoryPath = join4(projectDir, MEMORY_FILE);
-  if (existsSync4(memoryPath)) {
-    const lines = readFileSync4(memoryPath, "utf-8").split("\n").length;
+  const memoryPath = join2(projectDir, MEMORY_FILE);
+  if (existsSync2(memoryPath)) {
+    const lines = readFileSync2(memoryPath, "utf-8").split("\n").length;
     if (lines > 150) {
       issues.push({
         level: "warning",
@@ -256,14 +165,12 @@ function doctor(projectDir) {
 export {
   AGENTS_DIR,
   AGENTS_MD,
+  CUSTOM_FILE,
   MEMORY_DETAIL_FILE,
   MEMORY_FILE,
   SPEC_DIR,
   TASKS_FILE,
-  appendMemory,
   doctor,
-  readMemory,
-  readTasks,
   scaffold,
-  writeTasks
+  updateRouter
 };

package/docs/ARCHITECTURE.md

@@ -168,28 +168,21 @@ This document proposes a generalizable architecture for AI memory across codebas
 
 ---
 
-## IDE Integration Points
+## Integration Points
 
-### OpenCode
-- Reads: AGENTS.md (via plugin hook)
-- Plugin auto-injects: `.agents/MEMORY.md` context on session start
-- Plugin reminds: Update TASKS.md on session idle
-- Writes: Agent appends to MEMORY.md/TASKS.md/spec/
+By default, we scaffold `AGENTS.md` which acts as the root router for your AI coding assistant. This file contains rules and documentation maps that point to the `.agents/` folder.
 
-### GitHub Copilot (VSCode)
-- Reads: `.github/copilot-instructions.md` (GitHub convention)
-- copilot-instructions.md = same router format as AGENTS.md
-- Points to `.agents/MEMORY.md` + spec files
-- Writes: User includes `@save memory: <decision>` in chat → agent appends
+If your specific AI tool requires a different file name, you can simply symlink the `AGENTS.md` file:
 
-### Cursor / Windsurf
-- Reads: `.cursorrules` / `.windsurfrules` (IDE convention)
-- Same router format, points to `.agents/`
-- Writes: Agent rules instruct direct append
+```bash
+# Example: For Cursor
+ln -s AGENTS.md .cursorrules
 
-### CLI / Non-IDE Workflows
-- Humans can read/edit `.agents/` files directly
-- No special IDE integration needed
+# Example: For GitHub Copilot
+mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
+```
+
+This ensures a single source of truth (`AGENTS.md`) is maintained while providing backward compatibility with any tool.
 
 ---
 
@@ -219,12 +212,12 @@ This document proposes a generalizable architecture for AI memory across codebas
    - Keep `.memsearch/memory/` as archive (1 year retention)
    - Delete milvus.db
 
-### From .github/copilot-instructions.md (monolithic)
+### From Monolithic Config Files (e.g. .cursorrules)
 
 1. **Extract decisions** → `.agents/MEMORY.md`
 2. **Extract patterns** → `.agents/spec/patterns.md`
 3. **Extract commands** → `AGENTS.md`
-4. **Keep router** → update `.github/copilot-instructions.md` to point to `.agents/`
+4. **Keep router** → Create symlink from your old config file to `AGENTS.md`
 
 ---
 
@@ -254,10 +247,8 @@ This document proposes a generalizable architecture for AI memory across codebas
 ## Tooling Support
 
 ### CLI
-- ✓ `npx @vuau/agent-memory init` — scaffold structure (interactive or with flags)
-- ✓ `npx @vuau/agent-memory init --opencode` — OpenCode only
-- ✓ `npx @vuau/agent-memory init --copilot --cursor` — multiple IDEs
-- ✓ `npx @vuau/agent-memory init --all` — all IDEs
+- ✓ `npx @vuau/agent-memory init` — scaffold structure (`AGENTS.md` + `.agents/`)
+- ✓ `npx @vuau/agent-memory init --force` — overwrite existing files
 - ✓ `npx @vuau/agent-memory doctor` — validate structure
 - Planned: ✗ `report` — generate memory stats, archival suggestions
 

package/docs/ARCHITECTURE.vi.md

@@ -168,27 +168,21 @@ Tài liệu này đề xuất kiến trúc khả năng skalabiliti cho AI memory
 
 ---
 
-## IDE Integration Points
+## Điểm Tích Hợp
 
-### OpenCode
-- Reads: `AGENTS.md` (native)
-- Agents follow rules trong AGENTS.md
-- Writes: Agent appends đến MEMORY.md/TASKS.md/spec/
+Mặc định, chúng tôi scaffold `AGENTS.md` hoạt động như root router cho AI coding assistant của bạn. File này chứa các rules và documentation maps trỏ đến thư mục `.agents/`.
 
-### GitHub Copilot (VSCode)
-- Reads: `.github/copilot-instructions.md` (GitHub convention)
-- copilot-instructions.md = cùng router format với AGENTS.md
-- Points đến `.agents/MEMORY.md` + spec files
-- Writes: Agent follows rules → appends khi appropriate
+Nếu công cụ AI cụ thể của bạn yêu cầu một tên file khác, bạn có thể dễ dàng dùng symlink file `AGENTS.md`:
 
-### Cursor / Windsurf
-- Reads: `.cursorrules` / `.windsurfrules` (IDE convention)
-- Cùng router format, points đến `.agents/`
-- Writes: Agent rules instruct direct append
+```bash
+# Ví dụ: Cho Cursor
+ln -s AGENTS.md .cursorrules
 
-### CLI / Non-IDE Workflows
-- Humans có thể read/edit `.agents/` files trực tiếp
-- Không cần special IDE integration
+# Ví dụ: Cho GitHub Copilot
+mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
+```
+
+Điều này đảm bảo single source of truth (`AGENTS.md`) được duy trì trong khi cung cấp khả năng tương thích ngược với mọi công cụ.
 
 ---
 
@@ -218,12 +212,12 @@ Tài liệu này đề xuất kiến trúc khả năng skalabiliti cho AI memory
    - Keep `.memsearch/memory/` như archive (1 year retention)
    - Delete milvus.db
 
-### Từ .github/copilot-instructions.md (monolithic)
+### Từ Monolithic Config Files (vd: .cursorrules)
 
 1. **Extract decisions** → `.agents/MEMORY.md`
 2. **Extract patterns** → `.agents/spec/patterns.md`
 3. **Extract commands** → `AGENTS.md`
-4. **Keep router** → update `.github/copilot-instructions.md` để point đến `.agents/`
+4. **Keep router** → Tạo symlink từ config file cũ của bạn trỏ tới `AGENTS.md`
 
 ---
 
@@ -253,10 +247,8 @@ Tài liệu này đề xuất kiến trúc khả năng skalabiliti cho AI memory
 ## Công cụ Support
 
 ### CLI
-- ✓ `npx @vuau/agent-memory init` — scaffold structure (interactive hoặc với flags)
-- ✓ `npx @vuau/agent-memory init --opencode` — chỉ OpenCode
-- ✓ `npx @vuau/agent-memory init --copilot --cursor` — nhiều IDEs
-- ✓ `npx @vuau/agent-memory init --all` — tất cả IDEs
+- ✓ `npx @vuau/agent-memory init` — scaffold structure (`AGENTS.md` + `.agents/`)
+- ✓ `npx @vuau/agent-memory init --force` — ghi đè files có sẵn
 - ✓ `npx @vuau/agent-memory doctor` — validate structure
 - Planned: ✗ `report` — generate memory stats, archival suggestions
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vuau/agent-memory",
-  "version": "0.4.0",
-  "description": "Structured AI memory for codebases — works with GitHub Copilot, Cursor, Windsurf, VS Code, OpenCode, and 25+ AI tools",
+  "version": "0.5.0",
+  "description": "Structured AI memory for codebases — scaffolding CLI for OpenCode, Copilot, Cursor, Windsurf",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -21,6 +21,7 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
     "typescript": "^6.0.3"
   },

package/templates/AGENTS.md

@@ -1,22 +1,18 @@
 # {{PROJECT_NAME}} - AGENTS
 
-Router file for AI agents. Keep under 150 lines.
+Router file for AI agents.
+
+> **Note**: This file is automatically managed by `@vuau/agent-memory`.
+> Do not add project-specific rules here, as they may be overwritten by `agent-memory update`.
+>
+> 👉 **For project-specific rules, context, and document mapping, see `.agents/CUSTOM.md`**
 
 ## Priority
 1. User request first.
-2. This `AGENTS.md`.
-3. Spec files in `.agents/spec/`.
-4. If conflict remains, choose smallest safe change and state assumption.
-
-## Documentation Map
-
-| Task | Spec File |
-|------|-----------|
-| Past decisions (1-line) | `.agents/MEMORY.md` |
-| Past decisions (full context) | `.agents/MEMORY-DETAIL.md` |
-| Current work in progress | `.agents/TASKS.md` |
-
-> Add your own spec files to `.agents/spec/` and reference them here.
+2. The rules in `.agents/CUSTOM.md`.
+3. This `AGENTS.md`.
+4. Spec files in `.agents/spec/`.
+5. If conflict remains, choose smallest safe change and state assumption.
 
 ## Memory Protocol
 
@@ -41,5 +37,6 @@ Before ending a session with unfinished work, move items to `## In Progress` or
 
 ## Response Style
 - Concise, concrete, implementation-focused.
+- Propose the simplest solution first (KISS & YAGNI) before writing code.
 - If uncertain, say `I don't know`, then give fastest verification step.
 - Do not invent files, APIs, or command outputs.

package/templates/CUSTOM.md

@@ -0,0 +1,18 @@
+# Project Rules & Document Map
+
+This file contains project-specific rules, architectural decisions, and document mappings.
+Feel free to modify this file to suit your project's needs.
+
+## Documentation Map
+
+| Task | Spec File |
+|------|-----------|
+| Past decisions (1-line) | `.agents/MEMORY.md` |
+| Past decisions (full context) | `.agents/MEMORY-DETAIL.md` |
+| Current work in progress | `.agents/TASKS.md` |
+
+> Add your own spec files to `.agents/spec/` and reference them here.
+
+## Custom Rules
+
+- Add your project-specific rules here.