@dosx/agent-memory 0.0.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# Agent Memory
+
+**Agent Memory** is a project-local **Workspace Memory** for AI coding agents.
+It is a small set of versioned Markdown files in `.agents/memory/` — the shared
+source of truth between humans and agents — so work continues across sessions,
+tools, and teammates **without chat history** and **without external
+infrastructure** (no server, vector DB, or embeddings).
+
+Agents **read and write** that memory. A manual skill (`/agent-memory`)
+bootstraps and maintains it; optional lifecycle hooks add deterministic git
+checkpoints while you work.
+
+Supported harnesses: Cursor, Claude Code, Codex, OpenCode, Copilot, Gemini CLI.
+
+## Why
+
+- **Project memory, not chat memory.** Files in Git beat paste-from-yesterday
+  chats. Anyone (human or agent) can pick up from `.agents/memory/` alone.
+- **Plain Markdown.** Searchable with `grep`, reviewable in PRs, no new runtime.
+- **Progressive disclosure.** Always-load files stay short; detail lives in
+  on-demand files (`architecture.md`, `domains/*`, …).
+- **Inspired by Karpathy's [llm-wiki][llm-wiki]** (index, log, lint, small
+  cross-linked files), adapted from source ingestion to _project_ memory.
+
+## How it works
+
+Memory lives at `.agents/memory/` and separates **durable knowledge** from
+**operational state**:
+
+| File                      | Role                                                           |
+| ------------------------- | -------------------------------------------------------------- |
+| `instructions.md`         | Method: how agents read and maintain the memory.               |
+| `index.md`                | Map + loading policy (always-load vs on-demand).               |
+| `current.md`              | Shared project state (done / in progress / next).              |
+| `active-work/<branch>.md` | Per-branch scratchpad (no merge conflicts across branches).    |
+| `decisions.md`            | Decisions and **why**.                                         |
+| `log.md`                  | Chronological activity log (append at the bottom).             |
+
+Lazy files (`vision.md`, `architecture.md`, `patterns.md`, `mistakes.md`,
+`known-issues.md`, `domains/*`, `features/*`) appear only when there is real
+content.
+
+**Workflow:** before a task, agents read `index.md`, `current.md`, and their
+branch's `active-work` file; while working they keep those current; at
+checkpoints they flush with `/agent-memory sync`.
+
+Full method:
+[`skills/agent-memory/vendor/README.md`](./skills/agent-memory/vendor/README.md)
+and
+[`instructions.md`](./skills/agent-memory/vendor/memory/instructions.md).
+
+## Quick start
+
+```bash
+# Skill (primary)
+npx skills add diegoos/agent-memory --skill agent-memory
+```
+
+In your agent:
+
+```text
+/agent-memory init                 # auto-detect harnesses, or: init cursor
+/agent-memory bootstrap            # optional: populate memory from the repo
+/agent-memory install hooks cursor # print hook-install commands (skill never runs them)
+```
+
+Install lifecycle hooks with the `npx` CLI:
+
+```bash
+npx @dosx/agent-memory install hooks cursor
+# interactive menu (skill + hooks / skill only / hooks only):
+npx @dosx/agent-memory install cursor
+# or from a checkout: bash hooks/install-hooks.sh cursor
+```
+
+`init` wires each harness's **native instruction file** (for example Cursor
+`.cursor/rules/agent-memory.mdc`, Copilot
+`.github/instructions/agent-memory.instructions.md`, or `AGENTS.md` /
+`CLAUDE.md` / `GEMINI.md`). It does **not** create harness roots (`.cursor/`,
+`.claude/`, …) unless you ask — and it never copies hook scripts. Use
+`init <harness>` when you already know the agent.
+
+## The skill
+
+[`/agent-memory`](./skills/agent-memory) is **manual-only** (never auto-triggers):
+
+| Command                       | Does                                                              |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `/agent-memory help`          | List commands.                                                    |
+| `/agent-memory init`          | Create `.agents/memory/`; wire native instruction file(s).        |
+| `/agent-memory install hooks` | Print how to install/refresh hooks (user-run installer).          |
+| `/agent-memory update`        | Migrate scaffolding; never overwrites your content blindly.       |
+| `/agent-memory bootstrap`     | Analyze the project and populate the memory.                      |
+| `/agent-memory sync`          | Refresh `current.md` / active-work / `log.md` / `index.md`.       |
+| `/agent-memory lint`          | Broken links, orphans, stale per-branch files, consistency.       |
+
+## Hooks
+
+Optional lifecycle hooks keep `.agents/memory/` current **during** agent work
+with deterministic checkpoints (no LLM loops): session binding, _Touched files_,
+`log.md` path bullets on full checkpoints, `current.md` _In progress_ on session
+start.
+
+**Semantic** content stays agent-owned (or `/agent-memory sync`): decisions,
+progress notes, log summary/type, lazy files.
+
+Install steps, event matrix, and project-dir resolution:
+[`hooks/README.md`](./hooks/README.md).
+
+## Other install options
+
+**Manual skeleton** (no skill CLI):
+
+```bash
+git clone --branch 0.0.13 --depth 1 \
+  https://github.com/diegoos/agent-memory /tmp/agent-memory
+mkdir -p .agents
+cp -R /tmp/agent-memory/skills/agent-memory/vendor/memory .agents/memory
+```
+
+Then paste the agent-memory block from
+[`skills/agent-memory/references/agent-block.md`](./skills/agent-memory/references/agent-block.md)
+into your agent instructions file (keep the
+`<!-- <agent-memory> -->` … `<!-- </agent-memory> -->` markers so `update` can
+refresh only that block).
+
+## Repository layout
+
+```text
+agent-memory/
+├── bin/agent-memory.js         # npx CLI
+├── package.json
+├── hooks/                      # installer + harness configs (outside the skill)
+└── skills/agent-memory/        # SKILL.md + vendor/ + references/
+    └── vendor/                 # SoT: memory skeleton + UPDATE.md + method README
+```
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+[llm-wiki]: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

package/bin/agent-memory.js

@@ -0,0 +1,496 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..');
+const VERSION = require('../package.json').version;
+const INSTALL_HOOKS_SH = path.join(ROOT, 'hooks', 'install-hooks.sh');
+const REMOTE_SKILL_SOURCE = `diegoos/agent-memory#${VERSION}`;
+
+const CANONICAL_HARNESSES = new Set([
+  'cursor',
+  'claude',
+  'codex',
+  'opencode',
+  'copilot',
+  'gemini',
+]);
+
+const HARNESS_ALIASES = {
+  'claude-code': 'claude',
+  github: 'copilot',
+};
+
+/**
+ * Env keys forwarded to install-hooks.sh (keep in sync with OpenCode
+ * ENV_ALLOWLIST_EXACT + prefixes in hooks/opencode/agent-memory.ts).
+ */
+const ENV_ALLOWLIST_EXACT = new Set([
+  'PATH',
+  'HOME',
+  'USER',
+  'SHELL',
+  'TMPDIR',
+  'TMP',
+  'TEMP',
+  'LANG',
+  'TZ',
+  // Windows
+  'SystemRoot',
+  'SYSTEMROOT',
+  'windir',
+  'WINDIR',
+  'USERPROFILE',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  'ComSpec',
+  'COMSPEC',
+  'PATHEXT',
+  // Git / XDG (safe.directory and config discovery)
+  'XDG_CONFIG_HOME',
+  'XDG_DATA_HOME',
+  'GIT_CONFIG_GLOBAL',
+  'GIT_CONFIG_SYSTEM',
+  'GIT_CONFIG',
+]);
+
+const ESC = '\u001b';
+const CSI = `${ESC}[`;
+
+function normalizeHarness(name) {
+  if (CANONICAL_HARNESSES.has(name)) return name;
+  return HARNESS_ALIASES[name] || null;
+}
+
+function isTTY() {
+  return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+
+function skillsAddCommandText() {
+  return `npx --yes skills add ${REMOTE_SKILL_SOURCE} --skill agent-memory`;
+}
+
+function printHelp() {
+  console.log(`agent-memory ${VERSION}
+
+Hooks installer for @dosx/agent-memory. The skill is installed separately
+via npx skills add (not this CLI).
+
+Usage:
+  agent-memory install hooks <harness>
+  agent-memory install <harness>          # interactive menu (TTY)
+  agent-memory install skill              # redirect to npx skills add
+  agent-memory help
+
+Harnesses: cursor, claude (claude-code), codex, opencode, copilot (github), gemini
+
+Examples:
+  npx @dosx/agent-memory install hooks cursor
+  npx @dosx/agent-memory install cursor
+  npx skills add diegoos/agent-memory#${VERSION} --skill agent-memory
+`);
+}
+
+/** Always shell:false — argv must not be re-parsed by cmd.exe. */
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    stdio: 'inherit',
+    ...options,
+    shell: false,
+  });
+  if (result.error) {
+    console.error(`error: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.signal) {
+    process.exit(1);
+  }
+  if (result.status === null || result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function buildInstallerEnv() {
+  const env = {
+    AGENT_MEMORY_PROJECT_DIR:
+      process.env.AGENT_MEMORY_PROJECT_DIR || process.cwd(),
+    AGENT_MEMORY_VERSION: VERSION,
+  };
+  for (const key of Object.keys(process.env)) {
+    if (ENV_ALLOWLIST_EXACT.has(key) || key.startsWith('LC_')) {
+      const val = process.env[key];
+      if (val !== undefined) env[key] = val;
+    }
+  }
+  return env;
+}
+
+function runSkillsAdd() {
+  const args = [
+    '--yes',
+    'skills',
+    'add',
+    REMOTE_SKILL_SOURCE,
+    '--skill',
+    'agent-memory',
+  ];
+  const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+  run(npx, args);
+}
+
+function installHooks(harness) {
+  if (!fs.existsSync(INSTALL_HOOKS_SH)) {
+    console.error(`error: missing installer at ${INSTALL_HOOKS_SH}`);
+    process.exit(1);
+  }
+  const bash = process.platform === 'win32' ? 'bash.exe' : 'bash';
+  run(bash, [INSTALL_HOOKS_SH, harness], { env: buildInstallerEnv() });
+}
+
+function renderSelectLines(title, options, selected) {
+  const lines = [title, ''];
+  for (let i = 0; i < options.length; i++) {
+    const active = i === selected;
+    const prefix = active ? `${ESC}[1m› ` : '  ';
+    const suffix = active ? `${ESC}[22m` : '';
+    lines.push(`${prefix}${options[i].label}${suffix}`);
+  }
+  lines.push('', '↑/↓ or j/k · Enter confirm · Ctrl+C/Esc cancel');
+  return lines;
+}
+
+function clearRenderedLines(lineCount) {
+  for (let i = 0; i < lineCount; i++) {
+    process.stdout.write(`${CSI}1A${CSI}2K`);
+  }
+}
+
+/**
+ * Interactive single-select menu (TTY only). Returns the chosen option value.
+ * Aborts with exit 1 on Ctrl+C or Esc.
+ */
+function selectPrompt(title, options) {
+  return new Promise((resolve) => {
+    let selected = 0;
+    let renderedLineCount = 0;
+    let escState = 'normal';
+    let escTimer = null;
+    let rawModeEnabled = false;
+    const stdin = process.stdin;
+
+    function disableRawMode() {
+      if (rawModeEnabled && typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(false);
+        rawModeEnabled = false;
+      }
+    }
+
+    function clearEscTimer() {
+      if (escTimer) {
+        clearTimeout(escTimer);
+        escTimer = null;
+      }
+    }
+
+    function isCsiFinal(ch) {
+      const code = ch.charCodeAt(0);
+      return code >= 0x40 && code <= 0x7e;
+    }
+
+    function isAlphanumeric(ch) {
+      return /[0-9A-Za-z]/.test(ch);
+    }
+
+    function startEscTimer() {
+      clearEscTimer();
+      escTimer = setTimeout(() => {
+        escTimer = null;
+        if (escState === 'esc') {
+          escState = 'normal';
+          abort();
+          return;
+        }
+        if (escState === 'csi' || escState === 'ss3') {
+          escState = 'normal';
+        }
+      }, 50);
+    }
+
+    function moveUp() {
+      selected = (selected - 1 + options.length) % options.length;
+      redraw();
+    }
+
+    function moveDown() {
+      selected = (selected + 1) % options.length;
+      redraw();
+    }
+
+    function abort() {
+      cleanup();
+      process.stdout.write('\n');
+      process.exit(1);
+    }
+
+    function cleanup() {
+      clearEscTimer();
+      disableRawMode();
+      stdin.pause();
+      stdin.removeListener('data', onData);
+      stdin.removeListener('end', onEnd);
+    }
+
+    function printMenu() {
+      const lines = renderSelectLines(title, options, selected);
+      lines.forEach((line) => process.stdout.write(`${line}\n`));
+      renderedLineCount = lines.length;
+    }
+
+    function redraw() {
+      clearRenderedLines(renderedLineCount);
+      printMenu();
+    }
+
+    function processChar(ch) {
+      if (escState === 'esc') {
+        clearEscTimer();
+        if (ch === '[') {
+          escState = 'csi';
+          startEscTimer();
+          return;
+        }
+        if (ch === 'O') {
+          escState = 'ss3';
+          startEscTimer();
+          return;
+        }
+        if (isAlphanumeric(ch)) {
+          escState = 'normal';
+        } else {
+          escState = 'normal';
+          abort();
+          return;
+        }
+      }
+
+      if (escState === 'csi') {
+        if (!isCsiFinal(ch)) {
+          startEscTimer();
+          return;
+        }
+        clearEscTimer();
+        escState = 'normal';
+        if (ch === 'A') {
+          moveUp();
+          return;
+        }
+        if (ch === 'B') {
+          moveDown();
+          return;
+        }
+        return;
+      }
+
+      if (escState === 'ss3') {
+        if (!isCsiFinal(ch)) {
+          startEscTimer();
+          return;
+        }
+        clearEscTimer();
+        escState = 'normal';
+        if (ch === 'A') {
+          moveUp();
+          return;
+        }
+        if (ch === 'B') {
+          moveDown();
+          return;
+        }
+        return;
+      }
+
+      if (ch === '\u0003') {
+        abort();
+        return;
+      }
+      if (ch === ESC) {
+        escState = 'esc';
+        startEscTimer();
+        return;
+      }
+      if (ch === 'k') {
+        moveUp();
+        return;
+      }
+      if (ch === 'j') {
+        moveDown();
+        return;
+      }
+      if (ch === '\r' || ch === '\n') {
+        cleanup();
+        process.stdout.write('\n');
+        resolve(options[selected].value);
+      }
+    }
+
+    function onData(chunk) {
+      for (let i = 0; i < chunk.length; i++) {
+        processChar(chunk[i]);
+      }
+    }
+
+    function onEnd() {
+      abort();
+    }
+
+    let setupComplete = false;
+    try {
+      if (typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(true);
+        rawModeEnabled = true;
+      }
+      stdin.resume();
+      stdin.setEncoding('utf8');
+      stdin.on('data', onData);
+      stdin.on('end', onEnd);
+      printMenu();
+      setupComplete = true;
+    } finally {
+      if (!setupComplete) {
+        disableRawMode();
+      }
+    }
+  });
+}
+
+function failNonTTYInstallChoice(harness) {
+  console.error('error: interactive install requires a TTY.');
+  console.error(`  Hooks: npx @dosx/agent-memory install hooks ${harness}`);
+  console.error(`  Skill: ${skillsAddCommandText()}`);
+  process.exit(1);
+}
+
+function failNonTTYSkillsAdd() {
+  console.error('error: interactive install requires a TTY.');
+  console.error(`  Skill: ${skillsAddCommandText()}`);
+  process.exit(1);
+}
+
+async function promptInstallChoice(harness) {
+  if (!isTTY()) {
+    failNonTTYInstallChoice(harness);
+  }
+
+  const choice = await selectPrompt(`Install agent-memory for ${harness}:`, [
+    { label: 'Skill + hooks', value: 'both' },
+    { label: 'Skill only', value: 'skill' },
+    { label: 'Hooks only', value: 'hooks' },
+  ]);
+
+  if (choice === 'both') {
+    runSkillsAdd();
+    installHooks(harness);
+    return;
+  }
+  if (choice === 'skill') {
+    runSkillsAdd();
+    return;
+  }
+  installHooks(harness);
+}
+
+async function promptSkillsAddOrCancel() {
+  const choice = await selectPrompt('Continue?', [
+    { label: 'Run npx skills add', value: 'run' },
+    { label: 'Cancel', value: 'cancel' },
+  ]);
+
+  if (choice === 'run') {
+    runSkillsAdd();
+    return;
+  }
+  process.exit(0);
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  if (
+    args.length === 0 ||
+    args[0] === 'help' ||
+    args[0] === '--help' ||
+    args[0] === '-h'
+  ) {
+    printHelp();
+    return;
+  }
+
+  if (args[0] !== 'install') {
+    console.error(`error: unknown command: ${args[0]}`);
+    printHelp();
+    process.exit(1);
+  }
+
+  const rest = args.slice(1);
+  if (rest.length === 0) {
+    console.error('error: missing install target');
+    printHelp();
+    process.exit(1);
+  }
+
+  if (rest[0] === 'skill') {
+    if (rest.length > 1) {
+      console.error('error: install skill does not accept arguments');
+      process.exit(1);
+    }
+    if (!isTTY()) {
+      failNonTTYSkillsAdd();
+    }
+    console.log('This CLI installs hooks only. Install the skill with:');
+    console.log(`  ${skillsAddCommandText()}`);
+    await promptSkillsAddOrCancel();
+    return;
+  }
+
+  if (rest[0] === 'hooks') {
+    const raw = rest[1];
+    if (!raw) {
+      console.error('error: install hooks requires a harness argument');
+      printHelp();
+      process.exit(1);
+    }
+    if (rest.length > 2) {
+      console.error(`error: unexpected argument: ${rest[2]}`);
+      process.exit(1);
+    }
+    const harness = normalizeHarness(raw);
+    if (!harness) {
+      console.error(`error: unknown harness: ${raw}`);
+      printHelp();
+      process.exit(1);
+    }
+    installHooks(harness);
+    return;
+  }
+
+  const harness = normalizeHarness(rest[0]);
+  if (harness) {
+    if (rest.length > 1) {
+      console.error(`error: unexpected argument: ${rest[1]}`);
+      process.exit(1);
+    }
+    await promptInstallChoice(harness);
+    return;
+  }
+
+  console.error(`error: unknown install target: ${rest[0]}`);
+  printHelp();
+  process.exit(1);
+}
+
+main(process.argv).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});