@vuau/agent-memory 0.4.1 → 0.5.1

package/README.md

@@ -1,17 +1,12 @@
 # @vuau/agent-memory
 
-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.
+Structured AI memory for codebases. Works with GitHub Copilot, Cursor, Windsurf, and any AI coding assistant that reads markdown files.
 
 **[Tiếng Việt →](./README.vi.md)**
 
 ## Problem
 
-AI coding assistants lose context between sessions. They can't remember:
-- Architecture decisions you made last week
-- Code patterns specific to your project  
-- What task you were working on yesterday
-
-**agent-memory** solves this with a simple file-based memory system that any AI can read.
+AI coding assistants lose context between sessions. They can't remember architecture decisions, specific code patterns, or current tasks. **agent-memory** solves this with a simple file-based memory system that any AI can read and update.
 
 ## Quick Start
 
@@ -23,8 +18,9 @@ npx @vuau/agent-memory init
 
 ```
 / (Project Root)
-├── AGENTS.md                    # Root agent rules
+├── AGENTS.md                    # Fixed router (managed by package)
 └── .agents/
+    ├── CUSTOM.md                # Project-specific rules & spec mapping
     ├── MEMORY.md                # Long-term memory (decisions, patterns)
     ├── TASKS.md                 # Working memory (current tasks)
     └── spec/                    # Detailed specs (on-demand)
@@ -32,96 +28,40 @@ npx @vuau/agent-memory init
 
 ## How It Works
 
-1. **You run `init`** → Creates `AGENTS.md` + `.agents/` structure
-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 rules in `AGENTS.md` instruct the agent what to do.
+1. **You run `init`** → Creates the structure. `AGENTS.md` points to `.agents/CUSTOM.md`.
+2. **Agent reads rules** → Follows the priority: CUSTOM.md > AGENTS.md > spec files.
+3. **Agent works** → Updates MEMORY.md for decisions and TASKS.md for progress.
+4. **Update package** → Run `agent-memory update` to get the latest `AGENTS.md` router without losing your custom rules.
 
-## CLI Options
+## CLI Commands
 
 ```bash
-npx @vuau/agent-memory init [options]
-
-Options:
-  --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
-```
-
-## Memory Protocol
-
-Agents follow this protocol (defined in config files):
-
-```markdown
-## When to write
-- User approves a decision → append to .agents/MEMORY.md
-- Explore codebase/architecture → update .agents/spec/*.md
-- Start/finish a large task → update .agents/TASKS.md
-
-## Entry format
-- YYYY-MM-DD: <1-line decision or pattern>
-```
-
-### MEMORY.md Example
-
-```markdown
-## Patterns
-- 2026-04-24: State files = 3 layers (interfaces → defaults → variants)
-- 2026-04-24: Dumb components: initialState prop + optional callbacks
-
-## Decisions
-- 2026-04-06: Use useMediaQuery over CSS display:none for heavy components
+npx @vuau/agent-memory init      # Scaffold .agents/ structure
+npx @vuau/agent-memory update    # Update AGENTS.md router to latest version
+npx @vuau/agent-memory doctor    # Validate structure integrity
+npx @vuau/agent-memory help      # Show help
 ```
 
 ## Architecture
 
-### 4-Layer Design
-
-| Layer | File | Purpose |
-|-------|------|---------|
-| 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) |
-
-### Why File-Based?
-
-We tested memsearch, qmd, mem0, memories.sh — all failed for various reasons (see [RESEARCH.md](./docs/RESEARCH.md)):
-
-- **Context Blindness**: Auto-capture can't link user intent to prior analysis
-- **Context Bloat**: Fallback to transcripts costs 47k+ tokens
-- **Platform issues**: Dependencies don't work on Windows/VM
-
-File-based solution:
-- Agent writes when they understand context (quality > automation)
-- Plain markdown (portable, git-versionable, human-readable)
-- No dependencies (works everywhere)
+### The Router Split
 
-## Cross-IDE Compatibility
+- **AGENTS.md**: Core router managed by the package. Do not edit this file directly as it may be overwritten.
+- **.agents/CUSTOM.md**: Your project's home for custom rules, architectural decisions, and documentation mapping.
 
-By default, we only scaffold `AGENTS.md`, which is an emerging standard router file.
-
-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`:
-
-```bash
-# For Cursor
-ln -s AGENTS.md .cursorrules
-
-# For GitHub Copilot
-mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
-```
+### Memory Files
 
-All tools will read from the same underlying `.agents/` memory structure.
+| File | Purpose |
+|------|---------|
+| .agents/MEMORY.md | Curated decisions (1-line each) |
+| .agents/TASKS.md | Current work, next steps |
+| .agents/spec/*.md | Detailed technical documentation |
 
-## Documentation
+## Why File-Based?
 
-- **[RESEARCH.md](./docs/RESEARCH.md)** — Problem, experiments, comparison, why file-based wins
-- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer design, scalability, migration
+- **Context Precision**: AI writes when they understand context (quality > automation).
+- **Portable**: Plain markdown is portable, git-versionable, and human-readable.
+- **Minimalist**: No dependencies, no background processes, no API keys.
 
 ## License
 

package/README.vi.md

@@ -1,15 +1,12 @@
 # @vuau/agent-memory
 
-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ộ nhớ AI có cấu trúc cho các codebase. Hoạt động với GitHub Copilot, Cursor, Windsurf, và bất kỳ AI coding assistant nào đọc markdown files.
 
-## Bài toán
+**[English →](./README.md)**
 
-AI coding assistants mất bối cảnh giữa các phiên. Họ không thể nhớ:
-- Các quyết định kiến trúc bạn đã đưa ra tuần trước
-- Các mẫu thiết kế cụ thể của dự án
-- Task bạn đang làm hôm qua
+## Bài toán
 
-**agent-memory** giải quyết bằng hệ thống bộ nhớ đơn giản dựa trên file mà bất kỳ AI nào cũng có thể đọc.
+AI coding assistants mất bối cảnh giữa các phiên làm việc. Họ không thể nhớ các quyết định kiến trúc, các mẫu thiết kế cụ thể, hoặc các task đang làm dở. **agent-memory** giải quyết vấn đề này bằng một hệ thống bộ nhớ đơn giản dựa trên file mà bất kỳ AI nào cũng có thể đọc và cập nhật.
 
 ## Bắt đầu nhanh
 
@@ -21,105 +18,50 @@ npx @vuau/agent-memory init
 
 ```
 / (Project Root)
-├── AGENTS.md                    # Root agent rules
+├── AGENTS.md                    # Router cố định (quản lý bởi package)
 └── .agents/
-    ├── MEMORY.md                # Long-term memory (decisions, patterns)
-    ├── TASKS.md                 # Working memory (current tasks)
-    └── spec/                    # Detailed specs (on-demand)
+    ├── CUSTOM.md                # Rules riêng của project & mapping tài liệu
+    ├── MEMORY.md                # Bộ nhớ dài hạn (quyết định, patterns)
+    ├── TASKS.md                 # Bộ nhớ làm việc (tasks hiện tại)
+    └── spec/                    # Tài liệu kỹ thuật chi tiết (on-demand)
 ```
 
 ## Cách hoạt động
 
-1. **Bạn chạy `init`** → Tạo `AGENTS.md` + `.agents/` structure
-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.** Rules trong `AGENTS.md` hướng dẫn agent phải làm gì.
+1. **Bạn chạy `init`** → Tạo cấu trúc thư mục. `AGENTS.md` sẽ trỏ đến `.agents/CUSTOM.md`.
+2. **Agent đọc rules** → Tuân theo ưu tiên: CUSTOM.md > AGENTS.md > spec files.
+3. **Agent làm việc** → Cập nhật MEMORY.md cho các quyết định và TASKS.md cho tiến độ công việc.
+4. **Cập nhật package** → Chạy `agent-memory update` để nhận router `AGENTS.md` mới nhất mà không mất các rules tùy chỉnh của bạn.
 
-## CLI Options
+## Các lệnh CLI
 
 ```bash
-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)
-
-npx @vuau/agent-memory doctor   # Validate structure
-npx @vuau/agent-memory help     # Hiện help
-```
-
-## Memory Protocol
-
-Agents follow protocol này (defined trong config files):
-
-```markdown
-## Khi nào ghi
-- User approves decision → append vào .agents/MEMORY.md
-- Explore codebase/architecture → update .agents/spec/*.md
-- Start/finish large task → update .agents/TASKS.md
-
-## Entry format
-- YYYY-MM-DD: <1-line decision hoặc pattern>
-```
-
-### MEMORY.md Ví dụ
-
-```markdown
-## Patterns
-- 2026-04-24: State files = 3 layers (interfaces → defaults → variants)
-- 2026-04-24: Dumb components: initialState prop + optional callbacks
-
-## Decisions
-- 2026-04-06: Use useMediaQuery over CSS display:none cho heavy components
+npx @vuau/agent-memory init      # Khởi tạo cấu trúc .agents/
+npx @vuau/agent-memory update    # Cập nhật router AGENTS.md lên bản mới nhất
+npx @vuau/agent-memory doctor    # Kiểm tra tính toàn vẹn của cấu trúc
+npx @vuau/agent-memory help      # Hiện trợ giúp
 ```
 
 ## Kiến trúc
 
-### Thiết kế 4-Layer
-
-| Layer | File | Mục đích |
-|-------|------|----------|
-| 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) |
-
-### Tại sao File-Based?
-
-Chúng tôi đã test memsearch, qmd, mem0, memories.sh — tất cả failed vì nhiều lý do (xem [RESEARCH.md](./docs/RESEARCH.md)):
-
-- **Context Blindness**: Auto-capture không thể link user intent với prior analysis
-- **Context Bloat**: Fallback sang transcripts tốn 47k+ tokens
-- **Platform issues**: Dependencies không work trên Windows/VM
+### Phân tách Router
 
-File-based solution:
-- Agent ghi khi họ hiểu context (quality > automation)
-- Plain markdown (portable, git-versionable, human-readable)
-- Không dependencies (works everywhere)
+- **AGENTS.md**: Router cốt lõi được quản lý bởi thư viện. Không sửa file này trực tiếp vì nó có thể bị ghi đè khi update.
+- **.agents/CUSTOM.md**: Nơi dành riêng cho dự án của bạn để viết custom rules, quyết định kiến trúc và mapping tài liệu.
 
-## Cross-IDE Compatibility
-
-Mặc định, công cụ chỉ scaffold `AGENTS.md`, một chuẩn router file đang phổ biến.
-
-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`:
-
-```bash
-# Cho Cursor
-ln -s AGENTS.md .cursorrules
-
-# Cho GitHub Copilot
-mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md
-```
+### Các file bộ nhớ
 
-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/`.
+| File | Mục đích |
+|------|----------|
+| .agents/MEMORY.md | Các quyết định quan trọng (mỗi dòng 1 quyết định) |
+| .agents/TASKS.md | Công việc hiện tại và các bước tiếp theo |
+| .agents/spec/*.md | Tài liệu kỹ thuật chi tiết |
 
-## Tài liệu
+## Tại sao dùng File-Based?
 
-- **[RESEARCH.md](./docs/RESEARCH.md)** — Vấn đề, thử nghiệm, so sánh, tại sao file-based thắng
-- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — 4-layer design, scalability, migration
+- **Chính xác**: AI chỉ ghi dữ liệu khi đã hiểu rõ bối cảnh (chất lượng > tự động hóa).
+- **Linh hoạt**: Markdown đơn thuần, dễ di chuyển, có thể quản lý bằng Git và con người có thể đọc được.
+- **Tối giản**: Không phụ thuộc bên ngoài, không chạy ngầm, không cần API keys.
 
 ## License
 

package/dist/bin/cli.js

@@ -1,19 +1,24 @@
 #!/usr/bin/env node
 
-// src/core/scaffold.ts
+// bin/cli.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+
+// 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");
@@ -54,7 +59,8 @@ function scaffold(projectDir, options = {}) {
   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);
@@ -99,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 router file" },
+    { file: CUSTOM_FILE, desc: "Project specific rules" },
     { file: MEMORY_FILE, desc: "Long-term memory" },
     { file: TASKS_FILE, desc: "Working memory" }
   ];
@@ -162,6 +178,7 @@ function printUsage() {
 
 Usage:
   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
 
@@ -208,6 +225,26 @@ Initializing agent memory in ${cwd}...
   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("");
+}
 function runDoctor() {
   const cwd = process.cwd();
   const result = doctor(cwd);
@@ -234,6 +271,12 @@ switch (command) {
       process.exit(1);
     });
     break;
+  case "update":
+    runUpdate().catch((err) => {
+      console.error("Error:", err.message);
+      process.exit(1);
+    });
+    break;
   case "doctor":
     runDoctor();
     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");
@@ -52,7 +53,8 @@ function scaffold(projectDir, options = {}) {
   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);
@@ -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 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",
@@ -240,9 +149,9 @@ function doctor(projectDir) {
       });
     }
   }
-  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vuau/agent-memory",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Structured AI memory for codebases — scaffolding CLI for OpenCode, Copilot, Cursor, Windsurf",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,7 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
     "typescript": "^6.0.3"
   },
@@ -41,4 +42,4 @@
     "type": "git",
     "url": "git+https://github.com/vuau/agent-memory.git"
   }
-}
+}

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
 
@@ -40,6 +36,7 @@ Before ending a session with unfinished work, move items to `## In Progress` or
 - Do not create additional memory files outside `.agents/`.
 
 ## Response Style
-- Concise, concrete, implementation-focused.
+- Concrete, implementation-focused, caveman style (minimum words, zero fluff).
+- 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,13 @@
+# Project Rules & Document Map
+
+## Documentation Map
+
+| Area / Feature | Spec File |
+|----------------|-----------|
+| Example: Database Schema | `.agents/spec/database.md` |
+
+> Add your own spec files to `.agents/spec/` and reference them here.
+
+## Custom Rules
+
+- Add your project-specific rules here.

package/templates/MEMORY-DETAIL.md

@@ -1,8 +1,5 @@
 # Memory Detail
 
-Full Problem/Solution context for entries in MEMORY.md. Read on-demand when needing to understand *why* a decision was made.
-
----
 
 ## Example Category
 

package/templates/MEMORY.md

@@ -1,8 +1,5 @@
 # Project Memory
 
-Curated decisions, patterns, and pointers. Agents: read before implementing.
-
----
 
 ## Architecture
 <!-- Add pointers to spec files: → Full spec: `.agents/spec/architecture.md` -->

package/templates/TASKS.md

@@ -1,8 +1,5 @@
-# Current Tasks
+# Tasks
 
-Working memory for cross-session continuity. Update before ending a session.
-
----
 
 ## In Progress