@engramlabs/mcp 0.1.3-alpha → 0.1.4-alpha

package/README.md

@@ -1,47 +1,35 @@
 # @engramlabs/mcp
 
-Local-first agentic **knowledge & memory layer** for AI agents — via MCP.
+Local-first **knowledge & memory layer** for AI agents — via MCP.
 
-Engram gives your agent durable memory, source-grounded knowledge, a code
-graph, beliefs with contradiction detection, and governed retrieval — all in
-SQLite files on your machine. No cloud, no telemetry, no network calls on
-the default path.
+Durable memory, a code graph, beliefs, and governed retrieval in SQLite
+files on your machine. No cloud, no telemetry.
 
-## Install
+## Quick start
 
 ```bash
 npm install -g @engramlabs/mcp@alpha
+engram-mcp install --agent claude    # skills + hooks + red-forman subagent
 ```
 
-## Enable your MCP host + agent bundle
+Hosts: `claude` · `claude-desktop` · `cursor` · `codex` · `pi` · `copilot` · `all`
 
-One command — no JSON editing:
+**Project scope** — install skills, hooks, and agents into the repo
+(committed, shared with the team) instead of your home directory:
 
 ```bash
-engram-mcp install --agent claude          # skills + hooks + red-forman subagent
-# or: codex, copilot, pi, all
+cd your-repo
+engram-mcp install --agent claude --scope project
 ```
 
-MCP server registration only:
+Lands in `.claude/`, `.agents/skills/` (Codex + Copilot + pi read this
+cross-tool dir), `.codex/hooks.json`, `.github/hooks/`, `.pi/`.
 
-```bash
-engram-mcp install --client claude          # Claude Code
-engram-mcp install --client claude-desktop  # Claude Desktop
-engram-mcp install --client cursor          # Cursor
-engram-mcp install --client codex           # Codex CLI
-engram-mcp install --client pi              # pi
-engram-mcp install --client copilot         # GitHub Copilot / VS Code
-```
-
-Or run directly:
+MCP server only (no skills/hooks): `engram-mcp install --client <host>`
 
-```bash
-npx @engramlabs/mcp@alpha --storage ~/.engram
-```
+Or run directly: `npx @engramlabs/mcp@alpha --storage ~/.engram`
 
-### Manual configuration
-
-Add to your `.mcp.json` (or your host's config):
+### Manual config
 
 ```json
 {
@@ -58,40 +46,22 @@ Add to your `.mcp.json` (or your host's config):
 
 | | |
 |---|---|
-| **Remember** | `write_memory`, `store_knowledge` — decisions, observations, facts |
-| **Recall** | `recall`, `search`, `get_context` — fused multi-lane retrieval |
-| **Understand code** | `scan_repo` → `symbol_context`, `change_impact`, `architecture` |
-| **Read source** | `fetch_content` — stitch any indexed file's content back |
-| **Track beliefs** | `belief_get`, `contradiction_list` — derived stances, open tensions |
-| **Runbooks** | `procedure_put`, `procedure_list` — replayable with success/fail counters |
-| **Correct** | `forget`, `graph_health` — remove wrong data, monitor health |
-| **Adversarial review** | `red-forman` subagent — severity-tagged findings on any diff before you declare done |
+| **Memory** | remember decisions, gotchas, invariants — recall them automatically |
+| **Code graph** | index a repo → symbols, blast radius, architecture |
+| **Skills** | `engram-index/learn/search/plan/implement` — evidence-labeled workflows |
+| **Auto-recall** | hooks inject relevant memory per prompt; irrelevant stays silent |
+| **Adversarial review** | `red-forman` subagent — severity-tagged findings before you ship |
 
 ## Platforms
 
-| OS | Architecture | Binary size |
-|---|---|---|
-| Linux | x86-64 | ~49 MB |
-| Linux | ARM64 | ~49 MB |
-| macOS | Apple Silicon | ~49 MB |
-| Windows | x86-64 | ~49 MB |
-
-Platform binaries install automatically as optional dependencies — you
-don't need to pick one.
+Linux x64/ARM64 · macOS Apple Silicon · Windows x64 — binaries install
+automatically per machine.
 
 ## Privacy
 
-- All data lives in SQLite files under `--storage` (default: `~/.engram`)
-- No telemetry, ever
-- No cloud calls on the default path
-- Delete the storage directory = everything is gone
-
-## Learn more
-
-- [GitHub](https://github.com/phanijapps/engram) — source, architecture, docs
-- [HOW-TO](https://github.com/phanijapps/engram/blob/main/mcp/engram-mcp/HOW-TO.md) — full setup guide
-- [RFC-0021](https://github.com/phanijapps/engram/blob/main/docs/rfcs/0021-npm-distribution-rollout.md) — distribution design
+All data in SQLite under `~/.engram`. No telemetry, no cloud. Delete
+the directory = everything is gone.
 
-## License
+## Links
 
-MIT
+[GitHub](https://github.com/phanijapps/engram) · [Setup guide](https://github.com/phanijapps/engram/blob/main/mcp/engram-mcp/HOW-TO.md) · MIT

package/agent-install.js

@@ -147,16 +147,17 @@ function mergeClaudeHooks(file, entries, remove) {
 }
 
 const HOSTS = {
+  // USER scope installs to the home directory (available everywhere);
+  // PROJECT scope installs into the current repo (committed, per-team).
   claude: {
     label: 'Claude Code',
-    skillsDir: (home) => path.join(home, '.claude', 'skills'),
-    agentFile: (home) => [path.join(home, '.claude', 'agents'), 'red-forman.md'],
-    install(home, remove, written) {
-      copySkills(this.skillsDir(home), written);
-      const [agentDir, agentName] = this.agentFile(home);
-      if (remove) { try { fs.rmSync(path.join(agentDir, agentName)); } catch {} }
-      else copyAgent(agentDir, 'red-forman.claude.md', agentName, written);
-      const settings = path.join(home, '.claude', 'settings.json');
+    install(home, remove, written, cwd, scope) {
+      const root = scope === 'project' ? path.join(cwd, '.claude') : path.join(home, '.claude');
+      copySkills(path.join(root, 'skills'), written);
+      const agentDir = path.join(root, 'agents');
+      if (remove) { try { fs.rmSync(path.join(agentDir, 'red-forman.md')); } catch {} }
+      else copyAgent(agentDir, 'red-forman.claude.md', 'red-forman.md', written);
+      const settings = path.join(root, 'settings.json');
       const recall = hookScript('recall-context.cjs');
       const stale = hookScript('stale-index.cjs');
       mergeClaudeHooks(
@@ -173,40 +174,70 @@ const HOSTS = {
   },
   codex: {
     label: 'Codex',
-    skillsDir: (home) => path.join(home, '.agents', 'skills'),
-    install(home, remove, written) {
-      copySkills(this.skillsDir(home), written);
-      // Codex agents: ~/.codex/agents/*.yaml (YAML form — the TOML
-      // spelling is deprecated).
+    install(home, remove, written, cwd, scope) {
+      // Skills: the cross-tool .agents/skills dir (project) or ~/.agents/skills (user).
+      copySkills(
+        scope === 'project' ? path.join(cwd, '.agents', 'skills') : path.join(home, '.agents', 'skills'),
+        written,
+      );
+      // Agents: Codex discovers agents at user level only (~/.codex/agents,
+      // YAML form) — no documented project-agent location.
       const agentDir = path.join(home, '.codex', 'agents');
       if (remove) { try { fs.rmSync(path.join(agentDir, 'red-forman.yaml')); } catch {} }
-      else copyAgent(agentDir, 'red-forman.codex.yaml', 'red-forman.yaml', written);
+      else {
+        copyAgent(agentDir, 'red-forman.codex.yaml', 'red-forman.yaml', written);
+        if (scope === 'project') {
+          process.stdout.write('  note: Codex agents are user-scope (no project-agent discovery)\n');
+        }
+      }
       const recall = hookScript('recall-context.cjs');
       const stale = hookScript('stale-index.cjs');
-      const body = remove
-        ? null
-        : [
-            '[[hooks.UserPromptSubmit]]',
-            '  [[hooks.UserPromptSubmit.hooks]]',
-            '  type = "command"',
-            `  command = 'node "${recall}"'`,
-            '  async = true',
-            '  statusMessage = "engram recall"',
-            '',
-            '[[hooks.Stop]]',
-            '  [[hooks.Stop.hooks]]',
-            '  type = "command"',
-            `  command = 'node "${stale}"'`,
-            '',
-            '[[hooks.SessionStart]]',
-            '  matcher = "startup|resume"',
-            '  [[hooks.SessionStart.hooks]]',
-            '  type = "command"',
-            `  command = 'node "${recall}"'`,
-            '  additionalContextLimit = 2000',
-          ].join('\n');
-      writeTomlSection(path.join(home, '.codex', 'config.toml'), 'hooks', body);
-      written.push(path.join(home, '.codex', 'config.toml'));
+      if (scope === 'project') {
+        // Project hooks live in <repo>/.codex/hooks.json (JSON, not TOML).
+        const file = path.join(cwd, '.codex', 'hooks.json');
+        if (remove) {
+          try { fs.rmSync(file); } catch {}
+        } else {
+          writeJson(file, {
+            description: 'engram agent bundle (skills + hooks + subagent)',
+            hooks: {
+              UserPromptSubmit: [
+                { hooks: [{ type: 'command', command: `node "${recall}"`, async: true, statusMessage: 'engram recall' }] },
+              ],
+              Stop: [{ hooks: [{ type: 'command', command: `node "${stale}"` }] }],
+              SessionStart: [
+                { matcher: 'startup|resume', hooks: [{ type: 'command', command: `node "${recall}"`, additionalContextLimit: 2000 }] },
+              ],
+            },
+          });
+          written.push(file);
+        }
+      } else {
+        const body = remove
+          ? null
+          : [
+              '[[hooks.UserPromptSubmit]]',
+              '  [[hooks.UserPromptSubmit.hooks]]',
+              '  type = "command"',
+              `  command = 'node "${recall}"'`,
+              '  async = true',
+              '  statusMessage = "engram recall"',
+              '',
+              '[[hooks.Stop]]',
+              '  [[hooks.Stop.hooks]]',
+              '  type = "command"',
+              `  command = 'node "${stale}"'`,
+              '',
+              '[[hooks.SessionStart]]',
+              '  matcher = "startup|resume"',
+              '  [[hooks.SessionStart.hooks]]',
+              '  type = "command"',
+              `  command = 'node "${recall}"'`,
+              '  additionalContextLimit = 2000',
+            ].join('\n');
+        writeTomlSection(path.join(home, '.codex', 'config.toml'), 'hooks', body);
+        written.push(path.join(home, '.codex', 'config.toml'));
+      }
       if (!remove) {
         process.stdout.write('  note: run /hooks inside Codex to trust the new hooks\n');
       }
@@ -214,20 +245,24 @@ const HOSTS = {
   },
   copilot: {
     label: 'GitHub Copilot',
-    skillsDir: (home) => path.join(home, '.agents', 'skills'),
-    install(home, remove, written, cwd) {
-      copySkills(this.skillsDir(home), written);
-      // Copilot custom agents are repo-scoped: .github/agents/.
+    install(home, remove, written, cwd, scope) {
+      // Skills: .agents/skills (project, cross-tool) or ~/.agents/skills (user).
+      copySkills(
+        scope === 'project' ? path.join(cwd, '.agents', 'skills') : path.join(home, '.agents', 'skills'),
+        written,
+      );
+      // Agents: repo-scoped either way (.github/agents/).
       const agentDir = path.join(cwd || process.cwd(), '.github', 'agents');
       if (remove) { try { fs.rmSync(path.join(agentDir, 'red-forman.md')); } catch {} }
       else copyAgent(agentDir, 'red-forman.copilot.md', 'red-forman.md', written);
       // Per-prompt injection is not available to Copilot command hooks
       // (output dropped by design) — sessionStart only. Honest limitation.
-      const file = path.join(home, '.copilot', 'hooks', 'engram.json');
+      const file =
+        scope === 'project'
+          ? path.join(cwd, '.github', 'hooks', 'engram.json')
+          : path.join(home, '.copilot', 'hooks', 'engram.json');
       if (remove) {
-        try {
-          fs.rmSync(file);
-        } catch {}
+        try { fs.rmSync(file); } catch {}
       } else {
         writeJson(file, {
           version: 1,
@@ -241,17 +276,31 @@ const HOSTS = {
         });
         written.push(file);
       }
+      if (scope === 'project' && !remove) {
+        process.stdout.write('  note: commit .github/ and .agents/ so the team gets the bundle\n');
+      }
     },
   },
   pi: {
     label: 'pi',
-    skillsDir: (home) => path.join(home, '.pi', 'agent', 'skills'),
-    install(home, remove, written) {
-      copySkills(this.skillsDir(home), written);
-      const agentDir = path.join(home, '.pi', 'agent', 'agents');
+    install(home, remove, written, cwd, scope) {
+      // Skills: pi reads the cross-tool .agents/skills at project level
+      // (same dir codex/copilot read) or ~/.pi/agent/skills at user level.
+      copySkills(
+        scope === 'project' ? path.join(cwd, '.agents', 'skills') : path.join(home, '.pi', 'agent', 'skills'),
+        written,
+      );
+      // Agents: .pi/agents/ (project) or ~/.pi/agent/agents/ (user).
+      const agentDir =
+        scope === 'project' ? path.join(cwd, '.pi', 'agents') : path.join(home, '.pi', 'agent', 'agents');
       if (remove) { try { fs.rmSync(path.join(agentDir, 'red-forman.md')); } catch {} }
       else copyAgent(agentDir, 'red-forman.pi.md', 'red-forman.md', written);
-      const ext = path.join(home, '.pi', 'agent', 'extensions', 'engram-recall.cjs');
+      // Extensions are pi's hook mechanism: .pi/extensions/ (project)
+      // or ~/.pi/agent/extensions/ (user).
+      const ext =
+        scope === 'project'
+          ? path.join(cwd, '.pi', 'extensions', 'engram-recall.cjs')
+          : path.join(home, '.pi', 'agent', 'extensions', 'engram-recall.cjs');
       if (remove) {
         try {
           fs.rmSync(ext);
@@ -270,23 +319,30 @@ function agentInstall(args) {
   const cwd = process.cwd();
   let target = null;
   let remove = false;
+  let scope = 'user';
   let storage = process.env.ENGRAM_STORAGE || path.join(home, '.engram');
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--agent') target = args[++i];
     else if (args[i] === '--remove') remove = true;
+    else if (args[i] === '--scope') scope = args[++i];
     else if (args[i] === '--storage') storage = args[++i];
   }
+  if (scope !== 'user' && scope !== 'project') {
+    process.stderr.write(`engram-mcp install: --scope must be 'user' or 'project'\n`);
+    process.exit(1);
+  }
   if (!target || (target !== 'all' && !HOSTS[target])) {
     process.stderr.write(
       `engram-mcp install: ${target ? `unknown agent '${target}'` : 'missing --agent'}\n` +
         `Agents: ${Object.keys(HOSTS).join(', ')}, all\n` +
-        `Usage: engram-mcp install --agent <id> [--remove] [--storage <path>]\n`,
+        `Usage: engram-mcp install --agent <id> [--scope user|project] [--remove] [--storage <path>]\n`,
     );
     process.exit(1);
   }
   const ids = target === 'all' ? Object.keys(HOSTS) : [target];
   process.stdout.write(
     `${remove ? 'Removing' : 'Installing'} engram agent bundle (skills + hooks + subagents)\n` +
+      `  scope: ${scope}${scope === 'project' ? ` (${cwd})` : ''}\n` +
       `  storage: ${storage}\n\n`,
   );
   for (const id of ids) {
@@ -294,7 +350,7 @@ function agentInstall(args) {
     process.stdout.write(`[${host.label}]\n`);
     const written = [];
     try {
-      host.install(home, remove, written, cwd);
+      host.install(home, remove, written, cwd, scope);
       for (const w of written) process.stdout.write(`  ${remove ? 'cleaned' : 'wrote'}: ${w}\n`);
       if (id === 'copilot' && !remove) {
         process.stdout.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engramlabs/mcp",
-  "version": "0.1.3-alpha",
+  "version": "0.1.4-alpha",
   "description": "Local-first agentic memory: the engram MCP server launcher. Memory + knowledge graph + beliefs + code intelligence for any MCP client.",
   "license": "MIT",
   "repository": {
@@ -32,11 +32,11 @@
     "local-first"
   ],
   "optionalDependencies": {
-    "@engramlabs/mcp-linux-x64-gnu": "0.1.3-alpha",
-    "@engramlabs/mcp-linux-arm64-gnu": "0.1.3-alpha",
-    "@engramlabs/mcp-darwin-arm64": "0.1.3-alpha",
-    "@engramlabs/mcp-darwin-x64": "0.1.3-alpha",
-    "@engramlabs/mcp-win32-x64": "0.1.3-alpha"
+    "@engramlabs/mcp-linux-x64-gnu": "0.1.4-alpha",
+    "@engramlabs/mcp-linux-arm64-gnu": "0.1.4-alpha",
+    "@engramlabs/mcp-darwin-arm64": "0.1.4-alpha",
+    "@engramlabs/mcp-darwin-x64": "0.1.4-alpha",
+    "@engramlabs/mcp-win32-x64": "0.1.4-alpha"
   },
   "scripts": {
     "test": "node --test test/*.test.cjs"