@aabadin/project-memory-context 0.1.3 → 0.1.5

package/README.md

@@ -1,123 +1,568 @@
-# @aabadin/project-memory-context
+# @aabadin/project-memory-context (PMC)
 
-Portable project memory context CLI — bootstraps semantic enrichment workflows for any AI coding agent.
+Portable project memory context — bootstraps **semantic enrichment workflows** for any AI coding agent.
 
-This package installs and wires together:
+`pmc` installs, configures, and runs a complete pipeline that:
+1. **Maps** your codebase into a knowledge graph (via graphifyy)
+2. **Extracts** every top-level symbol (functions, classes, interfaces, etc.)
+3. **Enriches** each symbol with LLM-generated semantics (responsibility, inputs, outputs, dependencies)
+4. **Persists** everything as searchable memories that survive across sessions
 
-- a project bootstrapper (`pmc bootstrap` / `pmc setup`)
-- a local semantic MCP backed by Ollama (`pmc-local-model`)
-- an `agent-memory` MCP registration using `npx -y @aabadin/agent-memory-mcp`
-- command/workflow templates for `project-memory-context`
-- helper CLIs and artifact management for the semantic enrichment loop
+This gives your AI agent persistent, recallable knowledge of your entire codebase without re-reading files.
 
-## What it installs for you
+---
 
-The setup flow is designed to resolve everything automatically except:
+## Table of Contents
 
-- installing Ollama itself
-- pulling/downloading your local model
+- [Concept & Objective](#concept--objective)
+- [Architecture](#architecture)
+- [Models](#models)
+- [Installation](#installation)
+- [Setup](#setup)
+  - [Single-agent setup](#single-agent-setup)
+  - [Multi-agent setup](#multi-agent-setup--flags)
+  - [Automated detection](#automated-detection)
+- [CLI Reference](#cli-reference)
+  - [`pmc setup`](#pmc-setup)
+  - [`pmc bootstrap`](#pmc-bootstrap)
+  - [`pmc enrich` / `pmc enrich-queue`](#pmc-enrich--pmc-enrich-queue)
+  - [`pmc context`](#pmc-context)
+  - [`pmc status`](#pmc-status)
+  - [`pmc doctor`](#pmc-doctor)
+  - [`pmc init`](#pmc-init)
+  - [`pmc new-project`](#pmc-new-project)
+  - [`pmc sanitize`](#pmc-sanitize)
+  - [`pmc project-context`](#pmc-project-context)
+- [Environment Variables](#environment-variables)
+- [Project Structure](#project-structure)
+- [9 Base Project-Context Memories](#9-base-project-context-memories)
+- [Credits](#credits)
 
-The setup flow handles:
+---
 
-- asking for `OLLAMA_BASE_URL`
-- asking for `OLLAMA_MODEL`
-- installing `graphifyy` with Python/pip
-- creating `.planning/project-memory-context/`
-- writing project install state
-- registering MCP servers in `.mcp.json`
-- registering the plugin in `.opencode/opencode.json` when using OpenCode
-- copying `project-memory-context.md` and `project-memory-context workflow.md` into the target project
+## Concept & Objective
 
-## Install
+AI coding agents (OpenCode, Claude Code, Cursor, etc.) work within a single session. When a session ends, the agent forgets everything it learned about your codebase.
 
-Install the package globally, or run it with `npx`, then run setup inside the target repository.
+**Project-Memory-Context (PMC)** solves this by creating a **persistent semantic layer** between your codebase and your agent:
+
+| Component | What it does |
+|---|---|
+| **Visit (graphifyy)** | AST-level static analysis — builds a dependency graph of your entire codebase |
+| **Symbol extraction** | Regex+parser extraction of all top-level symbols (classes, functions, interfaces, etc.) |
+| **Semantic enrichment** | Calls a local LLM (Ollama) to describe each symbol's responsibility, inputs, outputs, and role |
+| **Agent Memory** | Stores each enriched symbol as a searchable vector memory (hybrid BM25 + semantic) |
+| **Project Context** | 9 auto-generated "base memories" about your project's stack, structure, architecture, etc. |
+
+The result: your agent can recall what a file does, how symbols connect, and what the project architecture looks like — across sessions, without re-scanning.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        PMC Package (@aabadin/...)                    │
+│                                                                     │
+│  cli/setup.mjs          cli/bootstrap.mjs       cli/enrich-queue.mjs│
+│  cli/context.mjs        cli/project-context.mjs  cli/doctor.mjs     │
+│  cli/build-worklist.mjs cli/enrich.mjs           cli/status.mjs     │
+│  cli/sanitize.mjs       cli/finalize.mjs         ...                │
+│                                                                     │
+│  ┌───────────────────────────────────────────────────────────────┐  │
+│  │  src/                           │  templates/                  │  │
+│  │  ├── providers/                 │  ├── opencode/ (commands,    │  │
+│  │  │   ├── local-model-provider   │  │    agents, autostart)     │  │
+│  │  │   └── cloud-api-provider     │  ├── claude-code/            │  │
+│  │  ├── extractors/ (stack,       │  ├── cursor/                 │  │
+│  │  │   structure, symbols)        │  └── generic/               │  │
+│  │  ├── retrieval/ (query-engine)  └───────────────────────────────┘  │
+│  │  ├── setup-bootstrap.mjs                                            │
+│  │  ├── template-installer.mjs                                        │
+│  │  ├── enrichment-driver.mjs                                         │
+│  │  ├── enrichment-config.mjs                                         │
+│  │  ├── sync-manifest.mjs                                             │
+│  │  ├── platform.mjs                                                  │
+│  │  └── ...                                                           │
+│  └────────────────────────────────────────────────────────────────    │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │  MCP Servers (installed by pmc setup)                        │   │
+│  │  ├── agent-memory  → npx -y @aabadin/agent-memory-mcp       │   │
+│  │  │                   (LanceDB + hybrid search)               │   │
+│  │  └── pmc-local-model → Ollama REST API                       │   │
+│  │                       (semantic enrichment via local LLM)    │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐   │
+│  │  External Dependencies                                        │   │
+│  │  ├── Ollama (local LLM for enrichment)                        │   │
+│  │  ├── graphifyy (Python pkg, AST-level knowledge graph)        │   │
+│  │  └── agent-memory-mcp (MCP server, hybrid BM25+vector DB)    │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Layer details
+
+**PMC CLI layer** (`cli/*.mjs`): Each file is a single command dispatchable via `pmc <command>`. They import from `src/` for shared logic.
+
+**PMC source layer** (`src/*.mjs`): Shared utilities, providers, extractors, and state management.
+
+**Agent Memory MCP** (`@aabadin/agent-memory-mcp`): A TypeScript MCP server backed by **LanceDB** with hybrid BM25 + vector search. Stores every enriched symbol as a searchable memory. Embeddings are generated locally using `Xenova/bge-m3` via ONNX — no API keys, no network after initial download. See [Credits](#credits) for the original repo.
+
+**Graphify** (`graphifyy`): A Python package by [obra](https://github.com/obra/graphify) that performs AST-level structural analysis of your codebase. Produces a `graph.json`, `graph.html`, and `GRAPH_REPORT.md` showing file-level dependencies, imports, and module clustering. No LLM calls during graph generation. See [Credits](#credits) for the original repo.
+
+---
+
+## Models
+
+### Embedding Model: `Xenova/bge-m3`
+
+| Property | Value |
+|---|---|
+| Model | [Xenova/bge-m3](https://huggingface.co/Xenova/bge-m3) |
+| Dimensions | 1024 |
+| Pooling | CLS (first token) |
+| Runtime | ONNX via `@huggingface/transformers` v4.2.0 |
+| Cache | Local ONNX model cache (~1 GB on first download) |
+| Provider | Runs entirely locally inside the `agent-memory-mcp` process |
+
+Used for: converting every memory into a dense vector for semantic similarity search. The ONNX runtime downloads the model once on first run and caches it locally — no network calls during normal operation.
+
+### LLM: `deepseek-coder-v2:16b-ctx32k` (Ollama)
+
+| Property | Value |
+|---|---|
+| Model | [deepseek-coder-v2](https://ollama.com/library/deepseek-coder-v2) |
+| Provider | [Ollama](http://localhost:11434) |
+| Context | 32K tokens |
+| Size | 16B parameters |
+| Hardware | Local GPU/CPU via Ollama |
+
+Used for: semantic enrichment — reading source code fragments and producing structured descriptions of each symbol's responsibility, inputs, outputs, dependencies, and role.
+
+**Alternative models** (configure via `OLLAMA_MODEL` env var):
+- `qwen3-coder:30b` — larger, better reasoning
+- `codellama:13b` — good for code tasks
+- `deepseek-coder-v2:16b-ctx32k` — default, best balance of speed and quality
+
+---
+
+## Installation
 
 ```bash
 npm install -g @aabadin/project-memory-context
-pmc setup
 ```
 
-Without a global install:
+Or run without installing:
 
 ```bash
 npx @aabadin/project-memory-context setup
 ```
 
-## Setup prompts
+**System requirements:**
+- Node.js ≥ 18
+- Ollama installed and running
+- Python 3 (for graphifyy)
+- ~2 GB free disk space (for embedding model cache + LanceDB)
+
+---
 
-`pmc setup` asks for:
+## Setup
 
-- Ollama base URL, default `http://localhost:11434`
-- Ollama model name, default `deepseek-coder-v2:16b-ctx32k`
+Run `pmc setup` in your project root:
 
-It then attempts to install:
+```bash
+cd /path/to/your/project
+pmc setup
+```
+
+The interactive prompt asks for:
+1. **Ollama base URL** (default: `http://localhost:11434`)
+2. **Ollama model name** (default: `deepseek-coder-v2:16b-ctx32k`)
+
+It then:
+1. Installs `graphifyy` via pip
+2. Creates `.planning/project-memory-context/` with full directory structure
+3. Writes MCP config for the target agent(s)
+4. Installs agent-specific templates (commands, agents config, autostart snippets)
+5. Runs the environment doctor to verify everything works
+
+### Single-agent setup
 
 ```bash
-python -m pip install graphifyy
+pmc setup                        # Auto-detects your agent
+pmc setup --opencode             # Force OpenCode
+pmc setup --claude               # Force Claude Code
+pmc setup --cursor               # Force Cursor
+pmc setup --generic              # Generic (writes README-SETUP.md)
 ```
 
-or an equivalent Python launcher depending on platform.
+### Multi-agent setup (combinable flags)
 
-## Resulting project files
+```bash
+pmc setup --opencode --claude                    # OpenCode + Claude Code
+pmc setup --opencode --claude --cursor           # All three
+pmc setup --opencode --cursor                    # OpenCode + Cursor only
+```
 
-After setup, the target project contains:
+Each agent gets its own configuration:
+- **OpenCode**: `.opencode/opencode.json` with `mcp.agent-memory` entry + `AGENTS.md` autostart + global commands/agents
+- **Claude Code**: `.claude/project-memory-context.json` enrichment config + `.mcp.json`
+- **Cursor**: `.cursor/project-memory-context.json` enrichment config + `.mcp.json`
+- **All agents**: `.mcp.json` at project root (universal fallback)
 
-```text
-.mcp.json
-.planning/project-memory-context/install.json
+### Automated detection
+
+When run without flags, `pmc setup` detects your agent by checking (in order):
+
+1. `.opencode/` directory → OpenCode
+2. `CLAUDE.md` file → Claude Code
+3. `.claude/` directory → Claude Code
+4. `.cursorrules` file → Cursor
+5. `.cursor/` directory → Cursor
+6. `~/.config/opencode/` exists → OpenCode (global)
+7. Otherwise → Generic
+
+---
+
+## CLI Reference
+
+### `pmc setup`
+
+Interactively bootstraps PMC in the current project.
+
+```bash
+pmc setup [--opencode] [--claude] [--cursor] [--generic]
+```
+
+| Flag | Description |
+|---|---|
+| `--opencode` | Install configs for OpenCode |
+| `--claude` | Install configs for Claude Code |
+| `--cursor` | Install configs for Cursor |
+| `--generic` | Generic setup (README only) |
+| *(no flags)* | Auto-detect agent(s) |
+
+**What it creates:**
+```
+.planning/
+  project-memory-context/
+    install.json
+    enrichment/
+    graph/
+    intake/
+    runs/
+    project-context/
+      detected/     (auto-detected metadata)
+      declared/     (user-declared metadata)
+      materialized/ (9 base memories)
+      markdown/     (human-readable context)
+      state/        (refresh state)
+.opencode/opencode.json            (if opencode)
+.claude/project-memory-context.json (if claude-code)
+.cursor/project-memory-context.json (if cursor)
+.mcp.json                          (universal MCP)
+AGENTS.md                          (autostart snippet, if opencode)
 project-memory-context.md
 project-memory-context workflow.md
 ```
 
-## Runtime layout
+---
+
+### `pmc bootstrap`
+
+Portable, non-interactive bootstrap for any repo. Runs all stages.
+
+```bash
+pmc bootstrap [target-repo] [--all] [--stage-a] [--stage-b] [--enrich]
+```
+
+| Argument / Flag | Description |
+|---|---|
+| `target-repo` | Path to the target repo (default: current dir) |
+| `--stage-a` | Intake + graphify structural mapping |
+| `--stage-b` | Symbol extraction + build enrichment worklist |
+| `--all` | Both stages |
+| `--enrich` | Start enrichment queue in background (requires at least one stage) |
+
+**Examples:**
+
+```bash
+# Full pipeline (setup + graphify + symbols + enrichment)
+pmc bootstrap . --all
+
+# Graphify only
+pmc bootstrap . --stage-a
+
+# Symbols + enrichment only (after graphify)
+pmc bootstrap . --stage-b --enrich
+
+# Custom model
+OLLAMA_MODEL=qwen3-coder:30b pmc bootstrap . --all --enrich
+```
+
+**Environment variables for bootstrap:**
+
+| Variable | Default | Description |
+|---|---|---|
+| `OLLAMA_URL` | `http://localhost:11434` | Ollama REST endpoint |
+| `OLLAMA_MODEL` | `deepseek-coder-v2:16b-ctx32k` | Ollama model |
+| `PMC_CONCURRENCY` | `8` | Parallel slots for worklist |
+| `PMC_GRAPHIFY_PATH` | *(auto-detect)* | Custom path to graphify executable |
+
+---
+
+### `pmc enrich` / `pmc enrich-queue`
+
+Run or start the semantic enrichment queue.
+
+```bash
+pmc enrich                        # One-shot enrichment
+pmc enrich-queue                  # Continuous queue (long-running)
+```
+
+The enrichment queue:
+1. Reads `worklist.json` for pending symbols
+2. For each symbol, extracts the source code fragment
+3. Calls the local Ollama LLM with a structured prompt
+4. Stores the result as a memory via `agent-memory-mcp`
+5. Updates `graph.json`, `symbol-index.json`, and `worklist.json`
+
+**Internal pipeline per symbol:**
+```
+Symbol → semantic-unit (code fragment + imports)
+       → local-model-provider (Ollama) → structured report
+       → normalize-semantic-report → memory payload
+       → agent-memory: store → memoryId
+       → finalize-enrichment (graph + index + worklist)
+```
 
-During workflow execution, artifacts accumulate under:
+---
 
-```text
-.planning/project-memory-context/
-  intake/
-  graph/
-  enrichment/
-  runs/
+### `pmc context`
+
+Render project context for the current directory or a specific target.
+
+```bash
+pmc context [target] [--refresh] [--depth compact|extended|deep|disk]
 ```
 
-## MCP servers
+| Option | Description |
+|---|---|
+| `target` | Symbol key or file path to focus on (default: project overview) |
+| `--refresh` | Re-detect files and refresh stale memories |
+| `--depth` | Output verbosity (default: `compact`) |
+
+Depth levels:
+- **compact** — symbol name + one-line summary
+- **extended** — full LLM-generated description
+- **deep** — includes all neighbors (depends on / depended by)
+- **disk** — includes raw source code
 
-The bootstrap flow writes `.mcp.json` with an `agent-memory` server that runs:
+---
+
+### `pmc status`
+
+Show enrichment progress and system health.
 
 ```bash
-npx -y @aabadin/agent-memory-mcp
+pmc status
 ```
 
-OpenCode plugin integration may also inject local MCP entries at runtime using values from `.planning/project-memory-context/install.json`:
+Output:
+```
+Enrichment config:
+  Preferred modes: local-model, cloud-api, agent-subagent
+  Local model: deepseek-coder-v2:16b-ctx32k @ http://localhost:11434
+
+Worklist:
+  Total symbols:    314
+  Pending:          201
+  Enriched:         87
+  Stale:            21
+  Failed:           5
+```
 
-- `pmc-local-model`
-- `pmc-agent-memory`
+---
 
-`pmc-local-model` exposes a semantic report tool backed by Ollama.
+### `pmc doctor`
 
-`pmc-agent-memory` points at the public `agent-memory-mcp` binary when plugin injection is used.
+Run environment diagnostics to check that all dependencies are available.
 
-## Workflow order
+```bash
+pmc doctor
+```
 
-1. `stage-a`
-   - intake
-   - brainstorming clarification
-   - graphify structural mapping
+Checks:
+- **node-version** — Node.js ≥ 18?
+- **python** — Python 3 available?
+- **graphifyy** — graphifyy package installed?
+- **ollama** — Ollama reachable?
+- **memory-db-path** — MEMORY_DB_PATH set and writable?
+- **embedding-cache** — EMBEDDING_CACHE_PATH configured?
 
-2. `stage-b`
-   - build worklist
-   - prepare semantic jobs
-   - call `pmc-local-model`
-   - materialize `*.memory.json`
-   - store/update in `pmc-agent-memory`
-   - materialize `*.result.json`
-   - finalize or fail each symbol
+---
 
-## Development verification
+### `pmc init`
 
-Run the local test suite:
+Initialize a fresh PMC project structure.
 
 ```bash
-node --test "tools/project-memory-context/tests/*.test.mjs"
+pmc init <project-root>
 ```
+
+Creates the `.planning/project-memory-context/` directory tree and default configuration files.
+
+---
+
+### `pmc new-project`
+
+Delegates to `bootstrap.mjs`. Same as `pmc bootstrap`.
+
+```bash
+pmc new-project <target-repo> [--all] [--stage-a] [--stage-b] [--enrich]
+```
+
+---
+
+### `pmc sanitize`
+
+Clean up stale enrichment artifacts and rebuild worklist state.
+
+```bash
+pmc sanitize
+```
+
+---
+
+### `pmc project-context`
+
+Materialize or refresh the 9 base project-context memories.
+
+```bash
+pmc project-context [--refresh]
+```
+
+| Flag | Description |
+|---|---|
+| *(none)* | Generate all 9 memories from scratch |
+| `--refresh` | Only refresh memories whose source files have changed |
+
+---
+
+## Environment Variables
+
+### PMC variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `PMC_CLOUD_API_KEY` | *(none)* | API key for cloud enrichment fallback |
+| `PMC_CONCURRENCY` | `8` | Parallel enrichment slots |
+| `PMC_GRAPHIFY_PATH` | *(auto-detect)* | Custom path to graphify executable |
+| `PMC_GRAPHIFY_BIN` | *(auto-detect)* | Alternative to `PMC_GRAPHIFY_PATH` |
+| `PMC_GLOBAL_CONFIG` | `~/.config/pmc` | Override global config directory |
+| `PMC_LOCAL_MODEL_BASE_URL` | `http://localhost:11434` | Ollama URL for enrichment |
+| `PMC_LOCAL_MODEL` | *(from setup)* | Ollama model for enrichment |
+
+### Agent Memory MCP variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `MEMORY_DB_PATH` | Yes | Path to LanceDB database directory |
+| `EMBEDDING_MODEL` | No | `Xenova/bge-m3` (default) |
+| `EMBEDDING_DIMENSIONS` | No | `1024` (inferred from model) |
+| `EMBEDDING_POOLING` | No | `cls` (inferred from model) |
+| `EMBEDDING_CACHE_PATH` | No | Content-addressed binary embedding cache |
+| `MEMORY_DECAY_HALF_LIFE` | No | `30` days (set `0` to disable) |
+| `ENABLE_HARDCOPY` | No | `true` to enable JSON file backup |
+| `HARDCOPY_PATH` | If hardcopy | Directory for JSON mirror files |
+
+---
+
+## Project Structure
+
+A project with PMC installed will have:
+
+```
+your-repo/
+├── .planning/
+│   └── project-memory-context/
+│       ├── install.json               # PMC install state
+│       ├── enrichment/
+│       │   ├── worklist.json          # All symbols + enrichment status
+│       │   ├── sync-manifest.json     # Pending agent-memory syncs
+│       │   ├── semantic-jobs.json     # Prepared LLM enrichment jobs
+│       │   ├── failures.json          # Failed enrichment attempts
+│       │   └── *.memory.json          # Per-symbol memory payloads
+│       ├── graph/
+│       │   ├── graph.json             # Knowledge graph (graphifyy output)
+│       │   ├── graph.html             # Visual knowledge graph
+│       │   ├── graph.metadata.json    # Graph metadata
+│       │   └── GRAPH_REPORT.md        # Human-readable graph report
+│       ├── intake/                    # Project description + goals
+│       ├── runs/                      # Run-specific artifacts
+│       └── project-context/
+│           ├── detected/              # Auto-detected context
+│           ├── declared/              # User-declared context
+│           ├── materialized/          # 9 base memories (JSON)
+│           ├── markdown/              # Human-readable context
+│           └── state/                 # Refresh state tracking
+├── .opencode/opencode.json            # OpenCode MCP config (if opencode)
+├── .claude/project-memory-context.json # Claude Code enrichment config
+├── .mcp.json                          # Universal MCP server config
+├── AGENTS.md                          # PMC autostart block
+├── project-memory-context.md          # Command template
+└── project-memory-context workflow.md # Workflow template
+```
+
+---
+
+## 9 Base Project-Context Memories
+
+When you run `pmc project-context`, PMC generates and stores 9 memories in `agent-memory`:
+
+| # | Memory Key | Description |
+|---|---|---|
+| 1 | `stack-runtime` | Language, framework, runtime version (from `package.json`, `tsconfig.json`, etc.) |
+| 2 | `stack-dependencies` | Key dependencies and their purposes |
+| 3 | `structure-topology` | Directory layout, module organization |
+| 4 | `structure-entrypoints` | Main entry points and build targets |
+| 5 | `architecture-overview` | High-level architectural patterns |
+| 6 | `architecture-data-flow` | Data flow and state management |
+| 7 | `technical-rules` | Code conventions, linting rules, config |
+| 8 | `intake-goals` | User-declared project goals and focus areas |
+| 9 | `intake-description` | Human-written project summary |
+
+These are refreshed automatically when their source files change (`--refresh` mode).
+
+---
+
+## Credits
+
+### Agent Memory MCP
+
+The `@aabadin/agent-memory-mcp` package is a **fork** of [adamrdrew/agent-memory-mcp](https://github.com/adamrdrew/agent-memory-mcp), published under the `@aabadin` scope on npm.
+
+**Original**: Adam Drew's [agent-memory-mcp](https://github.com/adamrdrew/agent-memory-mcp) is an MCP server for persistent agent memory backed by LanceDB with hybrid BM25 + vector search using local ONNX embeddings.
+
+**Modifications for this project:**
+- Published under `@aabadin` scope (original author did not publish to npm under `@brain` scope)
+- Version bumped to 2.0.0
+- All references updated from `@brain/` to `@aabadin/` scope
+- Fully compatible with the original API and tool set
+
+The `agent-memory-mcp` package provides the **persistence layer** — every enriched symbol, every project-context memory, and every user observation is stored via this MCP server. It runs `npx -y @aabadin/agent-memory-mcp` automatically when installed by `pmc setup`.
+
+### Graphifyy
+
+[graphifyy](https://github.com/obra/graphify) by obra is a Python package for AST-level structural analysis of codebases. It produces knowledge graphs showing file dependencies, imports, module clustering, and code organization — all without LLM calls.
+
+**Role in PMC:** Graphify generates the base knowledge graph (`graph.json`) that PMC uses to understand symbol locations, file dependencies, and module relationships. The graph is stored under `.planning/project-memory-context/graph/` and is consumed by the query engine for context-aware symbol lookups.
+
+---
+
+## License
+
+GPL-3.0-or-later — see [LICENSE](LICENSE).

package/cli/setup.mjs

@@ -12,15 +12,21 @@ import { installAgentTemplates } from '../src/template-installer.mjs';
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 
+const AGENT_FLAGS = {
+  '--opencode': 'opencode',
+  '--claude': 'claude-code',
+  '--cursor': 'cursor',
+  '--generic': 'generic',
+};
+
 function installGraphify() {
   const candidates = process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python'];
   for (const command of candidates) {
     const result = spawnSync(command, ['-m', 'pip', 'install', 'graphifyy'], { stdio: 'inherit' });
     if (result.status === 0) return command;
   }
-  const pythonUrl = 'https://www.python.org/downloads/';
   console.warn(`\n⚠  Could not install graphifyy automatically.`);
-  console.warn(`   Python not found? Download it from: ${pythonUrl}`);
+  console.warn(`   Python not found? Download it from: https://www.python.org/downloads/`);
   console.warn(`   Then run: pip install graphifyy\n`);
   return null;
 }
@@ -31,13 +37,13 @@ function spawnCheck(bin, args) {
 }
 
 function parseArgs(args) {
-  const parsed = { agent: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--agent' && args[i + 1]) {
-      parsed.agent = args[++i];
+  const agents = [];
+  for (const arg of args) {
+    if (AGENT_FLAGS[arg]) {
+      agents.push(AGENT_FLAGS[arg]);
     }
   }
-  return parsed;
+  return { agents };
 }
 
 const rl = createInterface({ input, output });
@@ -45,7 +51,17 @@ const cwd = resolve(process.cwd());
 
 try {
   console.log('\n─── pmc setup ───────────────────────────────────────\n');
-  const { agent: requestedAgent } = parseArgs(process.argv.slice(2));
+  const { agents: requestedAgents } = parseArgs(process.argv.slice(2));
+
+  let agents;
+  if (requestedAgents.length > 0) {
+    agents = [...new Set(requestedAgents)];
+    console.log(`  Target agents: ${agents.join(', ')}`);
+  } else {
+    const detected = detectSetupAgentType(cwd);
+    agents = [detected];
+    console.log(`  Auto-detected agent: ${detected}`);
+  }
 
   const ollamaBaseUrl =
     (await rl.question('Ollama base URL [http://localhost:11434]: ')).trim() ||
@@ -57,33 +73,33 @@ try {
 
   installGraphify();
 
-  const agent = detectSetupAgentType(cwd, { requestedAgent });
   const { globalConfig } = resolveConfigDirs(cwd);
-  console.log(`\n  Detected agent: ${agent}`);
 
   const result = await bootstrapProjectInstall({
     projectRoot: cwd,
     packageRoot,
     ollamaBaseUrl,
     ollamaModel,
-    agent,
+    agents,
   });
 
-  await installAgentTemplates({
-    projectRoot: cwd,
-    agent,
-    packageRoot,
-    globalConfigDir: agent === 'opencode' ? globalConfig : undefined,
-  });
-  console.log(`  Installed ${agent} templates.`);
+  for (const agent of agents) {
+    await installAgentTemplates({
+      projectRoot: cwd,
+      agent,
+      packageRoot,
+      globalConfigDir: agent === 'opencode' ? globalConfig : undefined,
+    });
+    console.log(`  ✓ Installed ${agent} templates.`);
+  }
 
   console.log('\n─── Installation complete ───────────────────────────\n');
   console.log(`  Memory DB path:     ${result.installState.memoryDbPath}`);
   console.log(`  Embedding cache:    ${result.installState.embeddingCachePath}`);
   console.log(`  MCP config:         ${result.configPath}`);
   console.log(`  Command template:   ${result.commandPath}`);
+  console.log(`  Agents configured:  ${agents.join(', ')}`);
 
-  // Run doctor to surface any remaining issues
   console.log('\n─── Environment check ───────────────────────────────\n');
   const env = {
     ...process.env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aabadin/project-memory-context",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Portable project memory context CLI — bootstraps semantic enrichment workflows for any AI coding agent.",
   "license": "GPL-3.0-or-later",
   "type": "module",

package/src/setup-bootstrap.mjs

@@ -1,9 +1,8 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
+import { dirname, join } from 'node:path';
 
 import { ensureProjectMemoryContextDirs, writeJsonArtifact } from './artifacts.mjs';
 import { PMC_ENRICHMENT_CONFIG_FILE } from './enrichment-config.mjs';
-import { resolveConfigDirs } from './platform.mjs';
 
 async function readJson(filePath, fallback) {
   try {
@@ -63,50 +62,65 @@ async function writeMcpJson(projectRoot, installState) {
   return mcpPath;
 }
 
-async function ensureAgentConfigRegistration(projectRoot, installState, agentType) {
-  if (agentType === 'opencode') {
-    const opencodeDir = join(projectRoot, '.opencode');
-    await mkdir(opencodeDir, { recursive: true });
-    const configPath = join(opencodeDir, 'opencode.json');
-    const config = await readJson(configPath, { $schema: 'https://opencode.ai/config.json' });
-    const existing = Array.isArray(config.plugin) ? config.plugin : [];
-    if (!existing.includes('@aabadin/project-memory-context')) {
-      config.plugin = [...existing, '@aabadin/project-memory-context'];
-    }
-    config.mcp = {
-      ...(config.mcp ?? {}),
-      ...buildOpencodeMcpConfig(installState).mcp,
-    };
-    await mkdir(dirname(configPath), { recursive: true });
-    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
-    await writeMcpJson(projectRoot, installState);
-    return configPath;
+async function ensureOpencodeConfig(projectRoot, installState) {
+  const opencodeDir = join(projectRoot, '.opencode');
+  await mkdir(opencodeDir, { recursive: true });
+  const configPath = join(opencodeDir, 'opencode.json');
+  const config = await readJson(configPath, { $schema: 'https://opencode.ai/config.json' });
+  const existing = Array.isArray(config.plugin) ? config.plugin : [];
+  if (!existing.includes('@aabadin/project-memory-context')) {
+    config.plugin = [...existing, '@aabadin/project-memory-context'];
   }
+  config.mcp = {
+    ...(config.mcp ?? {}),
+    ...buildOpencodeMcpConfig(installState).mcp,
+  };
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return configPath;
+}
 
-  const { projectConfig } = resolveConfigDirs(projectRoot);
-  const agentDir = basename(projectConfig);
-
-  if (agentDir === '.claude' || agentDir === '.cursor' || agentDir === '.pmc') {
-    const mcpPath = await writeMcpJson(projectRoot, installState);
-    const enrichPath = join(projectConfig, PMC_ENRICHMENT_CONFIG_FILE);
-    const existingConfig = await readJson(enrichPath, {});
-    const config = {
-      ...existingConfig,
-      enrichment: {
-        ...existingConfig.enrichment,
-        localModel: {
-          ...existingConfig.enrichment?.localModel,
-          baseUrl: installState.ollamaBaseUrl,
-          model: installState.ollamaModel,
-        },
+async function ensureEnrichmentConfig(projectRoot, configDir, installState) {
+  const enrichPath = join(configDir, PMC_ENRICHMENT_CONFIG_FILE);
+  const existingConfig = await readJson(enrichPath, {});
+  const config = {
+    ...existingConfig,
+    enrichment: {
+      ...existingConfig.enrichment,
+      localModel: {
+        ...existingConfig.enrichment?.localModel,
+        baseUrl: installState.ollamaBaseUrl,
+        model: installState.ollamaModel,
       },
-    };
-    await mkdir(dirname(enrichPath), { recursive: true });
-    await writeFile(enrichPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
-    return mcpPath;
+    },
+  };
+  await mkdir(dirname(enrichPath), { recursive: true });
+  await writeFile(enrichPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+}
+
+async function ensureAgentConfigs(projectRoot, installState, agents) {
+  let primaryConfigPath = null;
+
+  for (const agent of agents) {
+    if (agent === 'opencode') {
+      primaryConfigPath = primaryConfigPath ?? await ensureOpencodeConfig(projectRoot, installState);
+    }
+    if (agent === 'claude-code') {
+      const claudeDir = join(projectRoot, '.claude');
+      await mkdir(claudeDir, { recursive: true });
+      await ensureEnrichmentConfig(projectRoot, claudeDir, installState);
+      primaryConfigPath = primaryConfigPath ?? join(projectRoot, '.mcp.json');
+    }
+    if (agent === 'cursor') {
+      const cursorDir = join(projectRoot, '.cursor');
+      await mkdir(cursorDir, { recursive: true });
+      await ensureEnrichmentConfig(projectRoot, cursorDir, installState);
+      primaryConfigPath = primaryConfigPath ?? join(projectRoot, '.mcp.json');
+    }
   }
 
-  return writeMcpJson(projectRoot, installState);
+  await writeMcpJson(projectRoot, installState);
+  return primaryConfigPath ?? join(projectRoot, '.mcp.json');
 }
 
 async function copyTemplate(packageRoot, templateName, projectRoot) {
@@ -124,8 +138,10 @@ export async function bootstrapProjectInstall({
   ollamaBaseUrl,
   ollamaModel,
   embeddingCachePath,
+  agents = [],
   agent,
 }) {
+  const resolvedAgents = agents.length > 0 ? agents : (agent ? [agent] : ['generic']);
   const dirs = await ensureProjectMemoryContextDirs(projectRoot);
   const memoryDbPath = join(dirs.base, 'memory-db');
   const installState = {
@@ -139,7 +155,7 @@ export async function bootstrapProjectInstall({
 
   await mkdir(memoryDbPath, { recursive: true });
   await writeJsonArtifact(join(dirs.base, 'install.json'), installState);
-  const configPath = await ensureAgentConfigRegistration(projectRoot, installState, agent);
+  const configPath = await ensureAgentConfigs(projectRoot, installState, resolvedAgents);
   const commandPath = await copyTemplate(packageRoot, 'project-memory-context.md', projectRoot);
   const workflowPath = await copyTemplate(packageRoot, 'project-memory-context workflow.md', projectRoot);
 
@@ -148,5 +164,6 @@ export async function bootstrapProjectInstall({
     configPath,
     commandPath,
     workflowPath,
+    agents: resolvedAgents,
   };
 }

package/src/template-installer.mjs

@@ -91,10 +91,13 @@ async function installOpencode({ projectRoot, packageRoot, placeholders, globalC
   const globalDir = globalConfigDir;
 
   const commandTemplates = [
-    'opencode/commands/new-project.md',
+    'opencode/commands/map-project.md',
     'opencode/commands/get-context.md',
     'opencode/commands/sync-context.md',
     'opencode/commands/sanitize.md',
+    'opencode/commands/enrich-status.md',
+    'opencode/commands/doctor.md',
+    'opencode/commands/init-project.md',
   ];
 
   for (const tpl of commandTemplates) {

package/templates/claude-code/CLAUDE.md.snippet

@@ -2,7 +2,7 @@
 
 <!-- pmc:init -->
 
-When the user types `/new-project`, run:
+When the user types `/map-project`, run:
 
 ```bash
 {{PMC_BIN}} bootstrap . --all --enrich
@@ -14,6 +14,24 @@ When the user types `/get-context`, run:
 {{PMC_BIN}} context . --refresh
 ```
 
+When the user types `/enrich-status`, run:
+
+```bash
+{{PMC_BIN}} status .
+```
+
+When the user types `/doctor`, run:
+
+```bash
+{{PMC_BIN}} doctor
+```
+
+When the user types `/init-project`, run:
+
+```bash
+{{PMC_BIN}} init .
+```
+
 When the user types `/sync-context`, process `.planning/project-memory-context/enrichment/sync-manifest.json` and upsert pending entries into `agent-memory`.
 
 When the user types `/sanitize`, run:

package/templates/cursor/.cursorrules.snippet

@@ -2,7 +2,7 @@
 
 <!-- pmc:init -->
 
-When the user types "/new-project", run:
+When the user types "/map-project", run:
 
 ```bash
 {{PMC_BIN}} bootstrap . --all --enrich
@@ -14,6 +14,24 @@ When the user types "/get-context", run:
 {{PMC_BIN}} context . --refresh
 ```
 
+When the user types "/enrich-status", run:
+
+```bash
+{{PMC_BIN}} status .
+```
+
+When the user types "/doctor", run:
+
+```bash
+{{PMC_BIN}} doctor
+```
+
+When the user types "/init-project", run:
+
+```bash
+{{PMC_BIN}} init .
+```
+
 When the user types "/sync-context", process `.planning/project-memory-context/enrichment/sync-manifest.json` and upsert pending entries into `agent-memory`.
 
 When the user types "/sanitize", run:

package/templates/opencode/commands/doctor.md

@@ -0,0 +1,21 @@
+---
+name: doctor
+description: Run environment diagnostics — check Python, Ollama, Node, agent-memory, and graphify.
+argument-hint: ""
+allowed-tools:
+  - Bash
+---
+
+<objective>
+Run the PMC environment doctor to verify all dependencies are correctly installed and configured.
+</objective>
+
+<execution>
+Run:
+
+```bash
+{{PMC_BIN}} doctor
+```
+
+This checks: Node version, Python availability, graphifyy installation, Ollama connectivity, MEMORY_DB_PATH, and embedding cache path.
+</execution>

package/templates/opencode/commands/enrich-status.md

@@ -0,0 +1,21 @@
+---
+name: enrich-status
+description: Show enrichment progress — pending, enriched, stale, and failed symbols in the worklist.
+argument-hint: ""
+allowed-tools:
+  - Bash
+---
+
+<objective>
+Display the current enrichment queue status: how many symbols have been enriched, how many are pending, stale, or failed.
+</objective>
+
+<execution>
+Run:
+
+```bash
+{{PMC_BIN}} status .
+```
+
+This shows the worklist summary with counts for pending, enriched, stale, and failed symbols.
+</execution>

package/templates/opencode/commands/init-project.md

@@ -0,0 +1,21 @@
+---
+name: init-project
+description: Initialize PMC project structure — creates .planning/project-memory-context/ directory tree.
+argument-hint: ""
+allowed-tools:
+  - Bash
+---
+
+<objective>
+Initialize the PMC directory structure in the current project. Creates the .planning/project-memory-context/ hierarchy and default configuration.
+</objective>
+
+<execution>
+Run:
+
+```bash
+{{PMC_BIN}} init .
+```
+
+This creates the full directory tree under `.planning/project-memory-context/` with intake, graph, enrichment, project-context, and runs subdirectories.
+</execution>

package/templates/opencode/commands/{new-project.md → map-project.md}

@@ -1,5 +1,5 @@
 ---
-name: new-project
+name: map-project
 description: Bootstrap PMC in the current project with graphify, worklist, and base memories.
 argument-hint: "[--all] [--enrich]"
 allowed-tools: