@vuau/agent-memory 0.1.0

package/src/core/scaffold.ts

@@ -0,0 +1,124 @@
+/**
+ * Scaffold — create .agents/ directory structure in a project.
+ *
+ * Idempotent: skips existing files unless force=true.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs"
+import { join, resolve, dirname } from "path"
+import { fileURLToPath } from "url"
+import {
+  AGENTS_DIR,
+  SPEC_DIR,
+  MEMORY_FILE,
+  TASKS_FILE,
+  AGENTS_MD,
+  COPILOT_INSTRUCTIONS,
+  type AgentMemoryConfig,
+} from "./types.ts"
+
+// Resolve templates dir relative to this file (works in both Bun and Node)
+function getTemplatesDir(): string {
+  // Try import.meta based resolution
+  try {
+    const thisDir = dirname(fileURLToPath(import.meta.url))
+    const candidate = resolve(thisDir, "../../templates")
+    if (existsSync(candidate)) return candidate
+  } catch {}
+  // Fallback: walk up from __dirname if available
+  const candidate2 = resolve(__dirname, "../../templates")
+  if (existsSync(candidate2)) return candidate2
+  throw new Error("Cannot locate templates directory")
+}
+
+const TEMPLATES_DIR = getTemplatesDir()
+
+export interface ScaffoldResult {
+  created: string[]
+  skipped: string[]
+}
+
+function readTemplate(name: string): string {
+  const templatePath = join(TEMPLATES_DIR, name)
+  return readFileSync(templatePath, "utf-8")
+}
+
+function applyVars(content: string, vars: Record<string, string>): string {
+  let result = content
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll(`{{${key}}}`, value)
+  }
+  return result
+}
+
+export function scaffold(
+  projectDir: string,
+  config: AgentMemoryConfig = {},
+  force = false
+): ScaffoldResult {
+  const result: ScaffoldResult = { created: [], skipped: [] }
+  const projectName = config.projectName || guessProjectName(projectDir)
+  const vars = { PROJECT_NAME: projectName }
+
+  // Ensure directories exist
+  const dirs = [
+    join(projectDir, AGENTS_DIR),
+    join(projectDir, SPEC_DIR),
+  ]
+  if (config.copilotInstructions !== false) {
+    dirs.push(join(projectDir, ".github"))
+  }
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+    }
+  }
+
+  // Files to scaffold
+  const files: Array<{ target: string; template: string }> = [
+    { target: AGENTS_MD, template: "AGENTS.md" },
+    { target: MEMORY_FILE, template: "MEMORY.md" },
+    { target: TASKS_FILE, template: "TASKS.md" },
+  ]
+
+  if (config.copilotInstructions !== false) {
+    files.push({
+      target: COPILOT_INSTRUCTIONS,
+      template: "copilot-instructions.md",
+    })
+  }
+
+  // Write files
+  for (const { target, template } of files) {
+    const targetPath = join(projectDir, target)
+    if (existsSync(targetPath) && !force) {
+      result.skipped.push(target)
+      continue
+    }
+    const content = applyVars(readTemplate(template), vars)
+    writeFileSync(targetPath, content)
+    result.created.push(target)
+  }
+
+  // Create .gitkeep in spec/ if empty
+  const specKeep = join(projectDir, SPEC_DIR, ".gitkeep")
+  if (!existsSync(specKeep)) {
+    writeFileSync(specKeep, "")
+    result.created.push(`${SPEC_DIR}/.gitkeep`)
+  }
+
+  return result
+}
+
+function guessProjectName(dir: string): string {
+  // Try package.json
+  const pkgPath = join(dir, "package.json")
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"))
+      if (pkg.name) return pkg.name
+    } catch {}
+  }
+  // Fallback to directory name
+  return dir.split("/").pop() || "Project"
+}

package/src/core/tasks.ts

@@ -0,0 +1,77 @@
+/**
+ * Tasks — read/update operations for TASKS.md
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "fs"
+import { join } from "path"
+import { TASKS_FILE } from "./types.ts"
+
+export type TaskStatus = "in_progress" | "up_next" | "completed"
+
+export interface TaskItem {
+  content: string
+  status: TaskStatus
+}
+
+/**
+ * Read tasks grouped by status section.
+ */
+export function readTasks(projectDir: string): Record<TaskStatus, string[]> {
+  const filePath = join(projectDir, TASKS_FILE)
+  const result: Record<TaskStatus, string[]> = {
+    in_progress: [],
+    up_next: [],
+    completed: [],
+  }
+
+  if (!existsSync(filePath)) return result
+
+  const content = readFileSync(filePath, "utf-8")
+  let currentSection: TaskStatus | null = 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
+}
+
+/**
+ * Write tasks back to TASKS.md, preserving header structure.
+ */
+export function writeTasks(
+  projectDir: string,
+  tasks: Record<TaskStatus, string[]>
+): void {
+  const filePath = join(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") || ""}
+`
+  writeFileSync(filePath, content)
+}

package/src/core/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Core constants and types shared across all entry points.
+ */
+
+export const AGENTS_DIR = ".agents"
+export const SPEC_DIR = ".agents/spec"
+export const MEMORY_FILE = ".agents/MEMORY.md"
+export const TASKS_FILE = ".agents/TASKS.md"
+export const AGENTS_MD = "AGENTS.md"
+export const COPILOT_INSTRUCTIONS = ".github/copilot-instructions.md"
+
+export interface AgentMemoryConfig {
+  /** Project name used in templates */
+  projectName?: string
+  /** Custom spec categories to scaffold */
+  specFiles?: string[]
+  /** Whether to create .github/copilot-instructions.md */
+  copilotInstructions?: boolean
+}
+
+export interface DoctorResult {
+  ok: boolean
+  issues: DoctorIssue[]
+}
+
+export interface DoctorIssue {
+  level: "error" | "warning" | "info"
+  file: string
+  message: string
+}

package/src/opencode/plugin.ts

@@ -0,0 +1,97 @@
+/**
+ * OpenCode Plugin — Memory Lifecycle
+ *
+ * Hooks into session events to manage .agents/ structure:
+ * - session.created → auto-scaffold if missing, log status
+ * - session.idle → remind to update TASKS.md
+ * - tool.execute.after → track file edits
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { existsSync, readFileSync } from "fs"
+import { resolve } from "path"
+import { scaffold } from "../core/scaffold.ts"
+import { MEMORY_FILE, TASKS_FILE, AGENTS_MD, SPEC_DIR } from "../core/types.ts"
+
+export const MemoryLifecyclePlugin: Plugin = async ({ client, directory }) => {
+  const memoryFile = resolve(directory, MEMORY_FILE)
+  const tasksFile = resolve(directory, TASKS_FILE)
+  const agentsFile = resolve(directory, AGENTS_MD)
+
+  let editCount = 0
+  let specFilesEdited: string[] = []
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.created") {
+        // Auto-scaffold .agents/ if AGENTS.md exists but .agents/ doesn't
+        const hasAgentsMd = existsSync(agentsFile)
+        const hasMemory = existsSync(memoryFile)
+
+        if (!hasMemory && hasAgentsMd) {
+          // Project has AGENTS.md but no .agents/ — scaffold memory files only
+          try {
+            const result = scaffold(directory, { copilotInstructions: false })
+            if (result.created.length > 0) {
+              await client.tui.showToast({
+                body: {
+                  message: `Agent memory initialized: ${result.created.join(", ")}`,
+                  variant: "success",
+                },
+              })
+            }
+          } catch (err) {
+            await client.app.log({
+              body: {
+                service: "agent-memory",
+                level: "warn",
+                message: `Auto-scaffold failed: ${err}`,
+              },
+            })
+          }
+        }
+
+        // Reset session counters
+        editCount = 0
+        specFilesEdited = []
+
+        await client.app.log({
+          body: {
+            service: "agent-memory",
+            level: "info",
+            message: `Memory: ${hasMemory}, Tasks: ${existsSync(tasksFile)}`,
+          },
+        })
+      }
+
+      // Remind about TASKS.md on session idle if significant work was done
+      if (event.type === "session.idle" && editCount >= 3) {
+        if (existsSync(tasksFile)) {
+          const content = readFileSync(tasksFile, "utf-8")
+          const inProgressSection = content.split("## In Progress")[1]
+          if (inProgressSection?.trim()) {
+            await client.tui.showToast({
+              body: {
+                message: `${editCount} edits this session. Update .agents/TASKS.md before ending.`,
+                variant: "info",
+              },
+            })
+          }
+        }
+      }
+    },
+
+    "tool.execute.after": async (input) => {
+      if (input.tool === "edit" || input.tool === "write") {
+        editCount++
+        const filePath = (input as any).args?.filePath || ""
+        if (filePath.includes(SPEC_DIR)) {
+          const shortPath = filePath.split(SPEC_DIR + "/").pop() || filePath
+          if (!specFilesEdited.includes(shortPath)) {
+            specFilesEdited.push(shortPath)
+          }
+        }
+      }
+    },
+  }
+}

package/templates/AGENTS.md

@@ -0,0 +1,44 @@
+# {{PROJECT_NAME}} - AGENTS
+
+Router file for AI agents. Keep under 150 lines.
+
+## 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 & patterns | `.agents/MEMORY.md` |
+| Current work in progress | `.agents/TASKS.md` |
+
+> Add your own spec files to `.agents/spec/` and reference them here.
+
+## Memory Protocol
+
+### When to write
+- User approves a decision or pattern → append to `.agents/MEMORY.md`
+- Explore codebase/architecture → update relevant `.agents/spec/*.md`
+- Start/finish a large task → update `.agents/TASKS.md`
+
+### MEMORY.md entry format
+```
+- YYYY-MM-DD: <1-line decision or pattern>
+```
+Place under the appropriate category. Add `→ spec file` pointer if details belong in a spec.
+
+### TASKS.md update
+Before ending a session with unfinished work, move items to `## In Progress` or `## Up Next`.
+
+### Rules
+- Keep MEMORY.md entries to 1 line each. Details go in spec files.
+- If MEMORY.md > 150 lines, archive old entries.
+- Do not create additional memory files outside `.agents/`.
+
+## Response Style
+- Concise, concrete, implementation-focused.
+- If uncertain, say `I don't know`, then give fastest verification step.
+- Do not invent files, APIs, or command outputs.

package/templates/MEMORY.md

@@ -0,0 +1,17 @@
+# Project Memory
+
+Curated decisions, patterns, and pointers. Agents: read before implementing.
+
+---
+
+## Architecture
+<!-- Add pointers to spec files: → Full spec: `.agents/spec/architecture.md` -->
+
+## Decisions
+<!-- 1-line entries: - YYYY-MM-DD: <decision> -->
+
+## Patterns
+<!-- Reusable code patterns discovered during development -->
+
+## Workflow
+<!-- Development workflow decisions and tooling choices -->

package/templates/TASKS.md

@@ -0,0 +1,14 @@
+# Current Tasks
+
+Working memory for cross-session continuity. Update before ending a session.
+
+---
+
+## In Progress
+
+
+## Up Next
+
+
+## Completed
+

package/templates/copilot-instructions.md

@@ -0,0 +1,30 @@
+# {{PROJECT_NAME}} - Copilot Instructions (VSCode)
+
+Router file for GitHub Copilot. Points to shared agent documentation.
+
+## Priority
+1. Follow direct user request.
+2. Follow this file.
+3. Follow spec files in `.agents/spec/`.
+4. If conflict remains, choose smallest safe change and state assumptions.
+
+## Documentation Map
+
+| Task | Spec File |
+|------|-----------|
+| Past decisions & patterns | `.agents/MEMORY.md` |
+| Current work in progress | `.agents/TASKS.md` |
+
+> Add your own spec files to `.agents/spec/` and reference them here.
+
+## Response Style
+- Concise, concrete, implementation-focused.
+- If uncertain, say "I don't know" and give fastest verification step.
+- Do not invent files, APIs, or command results.
+- Keep diffs minimal, aligned with existing conventions.
+
+## Memory Protocol
+- When user approves a decision → append 1-line entry to `.agents/MEMORY.md` under appropriate category.
+- Format: `- YYYY-MM-DD: <decision>`.
+- Read `.agents/MEMORY.md` before implementing; follow spec file pointers for details.
+- Do not create additional memory files.