@vib795/agent-memory 0.1.4 → 0.1.6

package/README.md

@@ -102,6 +102,77 @@ agent-memory doctor                        preflight and health report
 
 Every command takes `--json`. Every cap lives in `config.json` and is tunable.
 
+### Where they run
+
+**Anywhere. There is one store per machine, not one per repository.** Everything
+lives under `~/.agents/memory`, nothing is written into the projects you point it
+at, and there is no per-repo setup step. `cd` between projects freely: the store
+does not move, split, or reset.
+
+One exception, and it is this repository rather than yours: if you installed from a
+clone, `npm install -g .` symlinks rather than copies, so `compact` regenerating the
+skill descriptions lands in your working tree and `skills/recall/SKILL.md` shows as
+modified. That is generated state, and [From a clone](#from-a-clone) says so. No
+project repository is ever written to.
+
+What the working directory changes is *scope*, never location.
+
+| Command | Reads | What the current repo changes |
+|---|---|---|
+| `init` | whole store | nothing |
+| `index` | whole store | nothing |
+| `compact` | whole store | nothing |
+| `doctor` | whole store | nothing |
+| `search` | whole store | nothing — full text hits every note in every repo |
+| `get` | whole store | the staleness line only; the note is found by id either way |
+| `tree` | whole store | **filters it** — defaults to the current repo |
+| `write` | whole store | **is stamped into the note** — see below |
+
+The current repo is `git rev-parse --show-toplevel` reduced to its directory name.
+Outside a git repository it is `null` and every command still works: `tree` comes
+back unscoped, and a new note carries no repo and no capture SHA, so it gets no
+staleness signal for the rest of its life.
+
+`write` is the one worth understanding, because it is the one that fixes facts in
+place. Run from `~/work/orders-api` it stamps `repos: [orders-api]`, records that
+repo's HEAD as `captured_sha`, and adds your `git config user.email` to the
+redactor's keep list so your own address survives while every other one is removed.
+Run the same JSON from your home directory and you get a note with no repo and no
+staleness anchor. **Capture from inside the repository the knowledge is about** —
+that is the whole reason `/remember` is worth invoking where you are working.
+
+Two flags that do not mean what they look like:
+
+- `agent-memory tree --repo`, with no value, means *all repos*. A bare `--repo`
+  clears the default scope rather than confirming it; `--repo <name>` points it at
+  a different repo.
+- `--all` is unrelated to scope. It prints every node instead of truncating to the
+  `treeLines` cap, which is what the `run agent-memory tree --all` hint at the
+  bottom of a truncated tree is telling you.
+
+One sharp edge: repo identity is the **directory name**, not the remote URL. Two
+clones both sitting in a directory called `utils` are one repo as far as the store
+is concerned. If you work across orgs, clone into distinct directory names.
+
+### How often they run
+
+Only `init` is a once-per-machine command, and `agent-memory setup` already ran it.
+
+| Command | When |
+|---|---|
+| `init` | once, via `setup`. Again only to register extra skill paths |
+| `write` | every capture |
+| `tree`, `get`, `search` | every lookup |
+| `index` | repair only — `write` reindexes on every call. Run it after hand-editing or deleting notes, or after deleting `index.db` |
+| `compact` | occasionally. Nothing schedules it: no daemon, no cron, no hook |
+| `doctor` | after install, after an upgrade, and whenever something looks wrong |
+
+**You will not type most of these.** `/remember` and `/handoff` call `write`;
+`/recall` calls `tree`, `get` and `search`. They are documented so you can see what
+the skills are doing and drive it by hand when you want to, but the daily loop is
+two slash commands in a chat box. The ones a person actually types are `setup`,
+`doctor`, and `compact` now and then.
+
 ## Install
 
 Two commands, and the second one is not optional:
@@ -144,7 +215,11 @@ routing digest.
 | Claude Code, CLI and VS Code extension | linked skill directory | `~/.claude/skills/<name>/` |
 | Codex CLI | linked skill directory | `$CODEX_HOME/skills/<name>/` |
 | VS Code, Insiders, VSCodium, Cursor, Windsurf | prompt file | `<user data>/prompts/<name>.prompt.md` |
-| Copilot CLI | *detected, skipped* | it documents no user-global prompt directory; use `.github/copilot-instructions.md` per repo |
+| GitHub Copilot CLI | linked skill directory | `~/.copilot/skills/<name>/` |
+
+GitHub documents two personal skill directories, `~/.copilot/skills` and
+`~/.agents/skills`, and Copilot reads both. The shared one is always written, so
+Copilot is served even on a machine that has never run the CLI.
 
 Prompt files are what GitHub Copilot chat reads, and they appear as `/recall`,
 `/remember` and `/handoff` in the chat box. They are **generated from the same
@@ -164,8 +239,38 @@ command is documented as part of the install. If you would rather have it automa
 npm install -g --allow-scripts=@vib795/agent-memory @vib795/agent-memory
 ```
 
-Either way `agent-memory doctor` tells you where you stand; it reports
-`skills linked: none registered` when setup has not run.
+Either way `agent-memory doctor` tells you where you stand. It checks the files
+rather than the tools, and names any agent it found that has no skills in it:
+
+```
+FAIL skills installed: GitHub Copilot CLI: handoff, recall, remember — run `agent-memory setup`
+```
+
+Detecting an agent is not the same as having installed into it, and a check that
+conflated the two would report healthy on exactly the machine where nothing ran.
+
+### The skills on their own
+
+The three skills are also published as [agent skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills),
+so they can be installed without the package:
+
+```bash
+gh skill install vib795/agent-memory --scope user
+```
+
+That gives you `/handoff`, `/remember` and `/recall` in every agent that reads the
+shared skill directories, and nothing else — no CLI, so no store. The skills say so
+when you run them and name the one command that fixes it. Use this to try the
+prompts; use npm when you want the memory.
+
+Claude Code can take the same three as a plugin:
+
+```
+/plugin marketplace add vib795/agent-memory
+/plugin install agent-memory@agent-memory
+```
+
+The same caveat applies: the plugin carries the skills, `npm` carries the store.
 
 Windows uses directory junctions, which need neither admin rights nor Developer
 Mode. On a network-backed profile (FSLogix, roaming) junctions fail and the skills
@@ -190,7 +295,7 @@ is generated state, and the committed value is only a placeholder.
 Needs Node 22.5 or newer; `doctor` says so plainly if the version is too old, and
 `postinstall` refuses rather than failing your install.
 
-Run `npm test` for the suite (71 tests, no dependencies). CI runs it on Linux,
+Run `npm test` for the suite (74 tests, no dependencies). CI runs it on Linux,
 macOS and Windows across Node 22 and 24, and separately installs the packed tarball
 and exercises it end to end on all three.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vib795/agent-memory",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Durable cross-repo knowledge graph for GitHub Copilot and Claude Code. Markdown source of truth, disposable SQLite index, zero runtime dependencies.",
   "keywords": [
     "github-copilot",

package/skills/handoff/SKILL.md

@@ -2,11 +2,8 @@
 name: handoff
 version: 0.1.0
 description: Capture the working state of the current conversation into a portable handoff file, so an agent in a different VS Code window or a different repository can continue the work without the user re-explaining it. Use when the user says handoff, hand this off, save context, wrap this up, or continue this elsewhere.
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Glob
+license: MIT
+allowed-tools: Bash Read Write Glob
 triggers:
   - handoff
   - hand this off

package/skills/recall/SKILL.md

@@ -2,9 +2,8 @@
 name: recall
 version: 0.1.0
 description: "Durable project knowledge: 5 notes, 1 constraint across agent-memory. Topics: memory store is markdown with a disposable sqlite cache, chose node:sqlite over better-sqlite3, sqlite recursive cte is the graph engine. Use when you need to know how a system works, why a decision was made, what convention applies, or what the environment forbids."
-allowed-tools:
-  - Bash
-  - Read
+license: MIT
+allowed-tools: Bash Read
 triggers:
   - how does this work
   - why did we
@@ -118,7 +117,11 @@ Rules that separate a useful recall from a confident wrong one:
 ## Failure handling
 
 - **`agent-memory: command not found`.** The package is not installed or not on
-  PATH. Say so and answer from the code; do not attempt to install it.
+  PATH. This is the expected state when the skill was installed on its own, with
+  `gh skill install`, rather than with the package. Answer from the code, then say
+  once that the store needs `npm install -g @vib795/agent-memory` (Node >= 22.5).
+  Do not run it yourself: installing a global package is the user's decision, and on
+  a managed desktop it is one they may not be free to make.
 - **Empty store.** Answer from the code, then mention `/remember` once.
 - **`doctor` reports a problem.** Report it in one line and continue. `index.db` is
   a cache; `agent-memory index` rebuilds it from the markdown, which is the source

package/skills/remember/SKILL.md

@@ -2,10 +2,8 @@
 name: remember
 version: 0.1.0
 description: Capture durable project knowledge from the current conversation into the shared memory graph, so a later conversation in any window or repository already knows it. Use when the user says remember this, save this, note this for later, or /remember.
-allowed-tools:
-  - Bash
-  - Read
-  - Write
+license: MIT
+allowed-tools: Bash Read Write
 triggers:
   - remember this
   - save this for later
@@ -149,7 +147,9 @@ Warnings from `write` are worth surfacing verbatim:
 
 - **Validation failed.** `write` reports every error at once. Fix them all and retry
   once. If it fails again, print the errors and stop; do not guess at the schema.
-- **`agent-memory: command not found`.** Say the package is not installed and print
-  the JSON in the chat so the work is not lost.
+- **`agent-memory: command not found`.** Print the JSON in the chat first, so the
+  work is not lost, then say the store needs `npm install -g @vib795/agent-memory`
+  (Node >= 22.5). Do not run it yourself. This is the expected state when the skill
+  was installed on its own with `gh skill install` rather than with the package.
 - **Nothing durable in the conversation.** Say so in one line. That is a correct
   outcome, not a failure.

package/src/cli.js

@@ -10,8 +10,9 @@ import { neighborhood, applyBudget } from './graph.js';
 import { buildTree, renderTree, buildDigest } from './digest.js';
 import { compact, maybeCompact } from './compact.js';
 import { staleness, currentRepo, reviewCandidates } from './staleness.js';
-import { setup as runSetup, unlinkSkills, danglingSkillLinks } from './setup.js';
-import { detectTargets } from './targets.js';
+import { setup as runSetup, unlinkSkills, danglingSkillLinks, SKILLS } from './setup.js';
+import { detectTargets, installableTargets } from './targets.js';
+import { join } from 'node:path';
 
 /**
  * One process, one answer.
@@ -473,6 +474,28 @@ function cmdDoctor() {
     agents.map((t) => `${t.label}${t.kind === 'unsupported' ? ' (skipped)' : ''}`).join('; '),
   );
 
+  // Detection is not installation, and conflating them is how this tool reports
+  // healthy while doing nothing. npm gates postinstall scripts behind allow-scripts,
+  // and managed profiles set ignore-scripts=true; in both cases the CLI lands on PATH
+  // and every agent directory stays empty, while every other check here still passes.
+  // So verify the files, per agent, rather than trusting that setup ever ran.
+  const gaps = [];
+  for (const t of installableTargets()) {
+    const absent = SKILLS.filter((name) =>
+      t.kind === 'skill-dir'
+        ? !existsSync(join(t.dir, name, 'SKILL.md'))
+        : !existsSync(join(t.dir, `${name}.prompt.md`)),
+    );
+    if (absent.length) gaps.push(`${t.label}: ${absent.join(', ')}`);
+  }
+  add(
+    'skills installed',
+    gaps.length === 0,
+    gaps.length
+      ? `${gaps.join('; ')} — run \`agent-memory setup\``
+      : `${SKILLS.length} in each of ${installableTargets().length} agents`,
+  );
+
   const dangling = danglingSkillLinks();
   add(
     'no broken skill links',

package/src/targets.js

@@ -115,18 +115,19 @@ export function detectTargets(home = agentHome()) {
     });
   }
 
-  // Detected and deliberately not written to. Copilot CLI documents no user-global
-  // prompt or skill directory, and writing into its config folder on a guess is how
-  // you ship a file that does nothing while claiming support for it.
-  const copilotCli = join(home, '.copilot');
-  if (existsSync(copilotCli)) {
+  // GitHub documents two personal skill directories, `~/.copilot/skills` and
+  // `~/.agents/skills`, and Copilot reads both. The `agents` entry above therefore
+  // already covers Copilot on a machine that has never run the CLI; this entry exists
+  // so that a machine which has one keeps its skills where its own docs say to look.
+  const copilotHome = join(home, '.copilot');
+  if (existsSync(copilotHome)) {
     targets.push({
       id: 'copilot-cli',
-      label: 'Copilot CLI',
-      kind: 'unsupported',
-      dir: copilotCli,
+      label: 'GitHub Copilot CLI',
+      kind: 'skill-dir',
+      dir: join(copilotHome, 'skills'),
       detected: true,
-      note: 'no user-global prompt directory; use .github/copilot-instructions.md per repo',
+      note: 'personal agent skills, same SKILL.md layout',
     });
   }