@aabadin/project-memory-context 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,123 +1,568 @@
1
- # @aabadin/project-memory-context
1
+ # @aabadin/project-memory-context (PMC)
2
2
 
3
- Portable project memory context CLI — bootstraps semantic enrichment workflows for any AI coding agent.
3
+ Portable project memory context — bootstraps **semantic enrichment workflows** for any AI coding agent.
4
4
 
5
- This package installs and wires together:
5
+ `pmc` installs, configures, and runs a complete pipeline that:
6
+ 1. **Maps** your codebase into a knowledge graph (via graphifyy)
7
+ 2. **Extracts** every top-level symbol (functions, classes, interfaces, etc.)
8
+ 3. **Enriches** each symbol with LLM-generated semantics (responsibility, inputs, outputs, dependencies)
9
+ 4. **Persists** everything as searchable memories that survive across sessions
6
10
 
7
- - a project bootstrapper (`pmc bootstrap` / `pmc setup`)
8
- - a local semantic MCP backed by Ollama (`pmc-local-model`)
9
- - an `agent-memory` MCP registration using `npx -y @aabadin/agent-memory-mcp`
10
- - command/workflow templates for `project-memory-context`
11
- - helper CLIs and artifact management for the semantic enrichment loop
11
+ This gives your AI agent persistent, recallable knowledge of your entire codebase without re-reading files.
12
12
 
13
- ## What it installs for you
13
+ ---
14
14
 
15
- The setup flow is designed to resolve everything automatically except:
15
+ ## Table of Contents
16
16
 
17
- - installing Ollama itself
18
- - pulling/downloading your local model
17
+ - [Concept & Objective](#concept--objective)
18
+ - [Architecture](#architecture)
19
+ - [Models](#models)
20
+ - [Installation](#installation)
21
+ - [Setup](#setup)
22
+ - [Single-agent setup](#single-agent-setup)
23
+ - [Multi-agent setup](#multi-agent-setup--flags)
24
+ - [Automated detection](#automated-detection)
25
+ - [CLI Reference](#cli-reference)
26
+ - [`pmc setup`](#pmc-setup)
27
+ - [`pmc bootstrap`](#pmc-bootstrap)
28
+ - [`pmc enrich` / `pmc enrich-queue`](#pmc-enrich--pmc-enrich-queue)
29
+ - [`pmc context`](#pmc-context)
30
+ - [`pmc status`](#pmc-status)
31
+ - [`pmc doctor`](#pmc-doctor)
32
+ - [`pmc init`](#pmc-init)
33
+ - [`pmc new-project`](#pmc-new-project)
34
+ - [`pmc sanitize`](#pmc-sanitize)
35
+ - [`pmc project-context`](#pmc-project-context)
36
+ - [Environment Variables](#environment-variables)
37
+ - [Project Structure](#project-structure)
38
+ - [9 Base Project-Context Memories](#9-base-project-context-memories)
39
+ - [Credits](#credits)
19
40
 
20
- The setup flow handles:
41
+ ---
21
42
 
22
- - asking for `OLLAMA_BASE_URL`
23
- - asking for `OLLAMA_MODEL`
24
- - installing `graphifyy` with Python/pip
25
- - creating `.planning/project-memory-context/`
26
- - writing project install state
27
- - registering MCP servers in `.mcp.json`
28
- - registering the plugin in `.opencode/opencode.json` when using OpenCode
29
- - copying `project-memory-context.md` and `project-memory-context workflow.md` into the target project
43
+ ## Concept & Objective
30
44
 
31
- ## Install
45
+ 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.
32
46
 
33
- Install the package globally, or run it with `npx`, then run setup inside the target repository.
47
+ **Project-Memory-Context (PMC)** solves this by creating a **persistent semantic layer** between your codebase and your agent:
48
+
49
+ | Component | What it does |
50
+ |---|---|
51
+ | **Visit (graphifyy)** | AST-level static analysis — builds a dependency graph of your entire codebase |
52
+ | **Symbol extraction** | Regex+parser extraction of all top-level symbols (classes, functions, interfaces, etc.) |
53
+ | **Semantic enrichment** | Calls a local LLM (Ollama) to describe each symbol's responsibility, inputs, outputs, and role |
54
+ | **Agent Memory** | Stores each enriched symbol as a searchable vector memory (hybrid BM25 + semantic) |
55
+ | **Project Context** | 9 auto-generated "base memories" about your project's stack, structure, architecture, etc. |
56
+
57
+ 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.
58
+
59
+ ---
60
+
61
+ ## Architecture
62
+
63
+ ```
64
+ ┌─────────────────────────────────────────────────────────────────────┐
65
+ │ PMC Package (@aabadin/...) │
66
+ │ │
67
+ │ cli/setup.mjs cli/bootstrap.mjs cli/enrich-queue.mjs│
68
+ │ cli/context.mjs cli/project-context.mjs cli/doctor.mjs │
69
+ │ cli/build-worklist.mjs cli/enrich.mjs cli/status.mjs │
70
+ │ cli/sanitize.mjs cli/finalize.mjs ... │
71
+ │ │
72
+ │ ┌───────────────────────────────────────────────────────────────┐ │
73
+ │ │ src/ │ templates/ │ │
74
+ │ │ ├── providers/ │ ├── opencode/ (commands, │ │
75
+ │ │ │ ├── local-model-provider │ │ agents, autostart) │ │
76
+ │ │ │ └── cloud-api-provider │ ├── claude-code/ │ │
77
+ │ │ ├── extractors/ (stack, │ ├── cursor/ │ │
78
+ │ │ │ structure, symbols) │ └── generic/ │ │
79
+ │ │ ├── retrieval/ (query-engine) └───────────────────────────────┘ │
80
+ │ │ ├── setup-bootstrap.mjs │
81
+ │ │ ├── template-installer.mjs │
82
+ │ │ ├── enrichment-driver.mjs │
83
+ │ │ ├── enrichment-config.mjs │
84
+ │ │ ├── sync-manifest.mjs │
85
+ │ │ ├── platform.mjs │
86
+ │ │ └── ... │
87
+ │ └──────────────────────────────────────────────────────────────── │
88
+ │ │
89
+ │ ┌──────────────────────────────────────────────────────────────┐ │
90
+ │ │ MCP Servers (installed by pmc setup) │ │
91
+ │ │ ├── agent-memory → npx -y @aabadin/agent-memory-mcp │ │
92
+ │ │ │ (LanceDB + hybrid search) │ │
93
+ │ │ └── pmc-local-model → Ollama REST API │ │
94
+ │ │ (semantic enrichment via local LLM) │ │
95
+ │ └──────────────────────────────────────────────────────────────┘ │
96
+ │ │
97
+ │ ┌──────────────────────────────────────────────────────────────┐ │
98
+ │ │ External Dependencies │ │
99
+ │ │ ├── Ollama (local LLM for enrichment) │ │
100
+ │ │ ├── graphifyy (Python pkg, AST-level knowledge graph) │ │
101
+ │ │ └── agent-memory-mcp (MCP server, hybrid BM25+vector DB) │ │
102
+ │ └──────────────────────────────────────────────────────────────┘ │
103
+ └─────────────────────────────────────────────────────────────────────┘
104
+ ```
105
+
106
+ ### Layer details
107
+
108
+ **PMC CLI layer** (`cli/*.mjs`): Each file is a single command dispatchable via `pmc <command>`. They import from `src/` for shared logic.
109
+
110
+ **PMC source layer** (`src/*.mjs`): Shared utilities, providers, extractors, and state management.
111
+
112
+ **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.
113
+
114
+ **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.
115
+
116
+ ---
117
+
118
+ ## Models
119
+
120
+ ### Embedding Model: `Xenova/bge-m3`
121
+
122
+ | Property | Value |
123
+ |---|---|
124
+ | Model | [Xenova/bge-m3](https://huggingface.co/Xenova/bge-m3) |
125
+ | Dimensions | 1024 |
126
+ | Pooling | CLS (first token) |
127
+ | Runtime | ONNX via `@huggingface/transformers` v4.2.0 |
128
+ | Cache | Local ONNX model cache (~1 GB on first download) |
129
+ | Provider | Runs entirely locally inside the `agent-memory-mcp` process |
130
+
131
+ 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.
132
+
133
+ ### LLM: `deepseek-coder-v2:16b-ctx32k` (Ollama)
134
+
135
+ | Property | Value |
136
+ |---|---|
137
+ | Model | [deepseek-coder-v2](https://ollama.com/library/deepseek-coder-v2) |
138
+ | Provider | [Ollama](http://localhost:11434) |
139
+ | Context | 32K tokens |
140
+ | Size | 16B parameters |
141
+ | Hardware | Local GPU/CPU via Ollama |
142
+
143
+ Used for: semantic enrichment — reading source code fragments and producing structured descriptions of each symbol's responsibility, inputs, outputs, dependencies, and role.
144
+
145
+ **Alternative models** (configure via `OLLAMA_MODEL` env var):
146
+ - `qwen3-coder:30b` — larger, better reasoning
147
+ - `codellama:13b` — good for code tasks
148
+ - `deepseek-coder-v2:16b-ctx32k` — default, best balance of speed and quality
149
+
150
+ ---
151
+
152
+ ## Installation
34
153
 
35
154
  ```bash
36
155
  npm install -g @aabadin/project-memory-context
37
- pmc setup
38
156
  ```
39
157
 
40
- Without a global install:
158
+ Or run without installing:
41
159
 
42
160
  ```bash
43
161
  npx @aabadin/project-memory-context setup
44
162
  ```
45
163
 
46
- ## Setup prompts
164
+ **System requirements:**
165
+ - Node.js ≥ 18
166
+ - Ollama installed and running
167
+ - Python 3 (for graphifyy)
168
+ - ~2 GB free disk space (for embedding model cache + LanceDB)
169
+
170
+ ---
47
171
 
48
- `pmc setup` asks for:
172
+ ## Setup
49
173
 
50
- - Ollama base URL, default `http://localhost:11434`
51
- - Ollama model name, default `deepseek-coder-v2:16b-ctx32k`
174
+ Run `pmc setup` in your project root:
52
175
 
53
- It then attempts to install:
176
+ ```bash
177
+ cd /path/to/your/project
178
+ pmc setup
179
+ ```
180
+
181
+ The interactive prompt asks for:
182
+ 1. **Ollama base URL** (default: `http://localhost:11434`)
183
+ 2. **Ollama model name** (default: `deepseek-coder-v2:16b-ctx32k`)
184
+
185
+ It then:
186
+ 1. Installs `graphifyy` via pip
187
+ 2. Creates `.planning/project-memory-context/` with full directory structure
188
+ 3. Writes MCP config for the target agent(s)
189
+ 4. Installs agent-specific templates (commands, agents config, autostart snippets)
190
+ 5. Runs the environment doctor to verify everything works
191
+
192
+ ### Single-agent setup
54
193
 
55
194
  ```bash
56
- python -m pip install graphifyy
195
+ pmc setup # Auto-detects your agent
196
+ pmc setup --opencode # Force OpenCode
197
+ pmc setup --claude # Force Claude Code
198
+ pmc setup --cursor # Force Cursor
199
+ pmc setup --generic # Generic (writes README-SETUP.md)
57
200
  ```
58
201
 
59
- or an equivalent Python launcher depending on platform.
202
+ ### Multi-agent setup (combinable flags)
60
203
 
61
- ## Resulting project files
204
+ ```bash
205
+ pmc setup --opencode --claude # OpenCode + Claude Code
206
+ pmc setup --opencode --claude --cursor # All three
207
+ pmc setup --opencode --cursor # OpenCode + Cursor only
208
+ ```
62
209
 
63
- After setup, the target project contains:
210
+ Each agent gets its own configuration:
211
+ - **OpenCode**: `.opencode/opencode.json` with `mcp.agent-memory` entry + `AGENTS.md` autostart + global commands/agents
212
+ - **Claude Code**: `.claude/project-memory-context.json` enrichment config + `.mcp.json`
213
+ - **Cursor**: `.cursor/project-memory-context.json` enrichment config + `.mcp.json`
214
+ - **All agents**: `.mcp.json` at project root (universal fallback)
64
215
 
65
- ```text
66
- .mcp.json
67
- .planning/project-memory-context/install.json
216
+ ### Automated detection
217
+
218
+ When run without flags, `pmc setup` detects your agent by checking (in order):
219
+
220
+ 1. `.opencode/` directory → OpenCode
221
+ 2. `CLAUDE.md` file → Claude Code
222
+ 3. `.claude/` directory → Claude Code
223
+ 4. `.cursorrules` file → Cursor
224
+ 5. `.cursor/` directory → Cursor
225
+ 6. `~/.config/opencode/` exists → OpenCode (global)
226
+ 7. Otherwise → Generic
227
+
228
+ ---
229
+
230
+ ## CLI Reference
231
+
232
+ ### `pmc setup`
233
+
234
+ Interactively bootstraps PMC in the current project.
235
+
236
+ ```bash
237
+ pmc setup [--opencode] [--claude] [--cursor] [--generic]
238
+ ```
239
+
240
+ | Flag | Description |
241
+ |---|---|
242
+ | `--opencode` | Install configs for OpenCode |
243
+ | `--claude` | Install configs for Claude Code |
244
+ | `--cursor` | Install configs for Cursor |
245
+ | `--generic` | Generic setup (README only) |
246
+ | *(no flags)* | Auto-detect agent(s) |
247
+
248
+ **What it creates:**
249
+ ```
250
+ .planning/
251
+ project-memory-context/
252
+ install.json
253
+ enrichment/
254
+ graph/
255
+ intake/
256
+ runs/
257
+ project-context/
258
+ detected/ (auto-detected metadata)
259
+ declared/ (user-declared metadata)
260
+ materialized/ (9 base memories)
261
+ markdown/ (human-readable context)
262
+ state/ (refresh state)
263
+ .opencode/opencode.json (if opencode)
264
+ .claude/project-memory-context.json (if claude-code)
265
+ .cursor/project-memory-context.json (if cursor)
266
+ .mcp.json (universal MCP)
267
+ AGENTS.md (autostart snippet, if opencode)
68
268
  project-memory-context.md
69
269
  project-memory-context workflow.md
70
270
  ```
71
271
 
72
- ## Runtime layout
272
+ ---
273
+
274
+ ### `pmc bootstrap`
275
+
276
+ Portable, non-interactive bootstrap for any repo. Runs all stages.
277
+
278
+ ```bash
279
+ pmc bootstrap [target-repo] [--all] [--stage-a] [--stage-b] [--enrich]
280
+ ```
281
+
282
+ | Argument / Flag | Description |
283
+ |---|---|
284
+ | `target-repo` | Path to the target repo (default: current dir) |
285
+ | `--stage-a` | Intake + graphify structural mapping |
286
+ | `--stage-b` | Symbol extraction + build enrichment worklist |
287
+ | `--all` | Both stages |
288
+ | `--enrich` | Start enrichment queue in background (requires at least one stage) |
289
+
290
+ **Examples:**
291
+
292
+ ```bash
293
+ # Full pipeline (setup + graphify + symbols + enrichment)
294
+ pmc bootstrap . --all
295
+
296
+ # Graphify only
297
+ pmc bootstrap . --stage-a
298
+
299
+ # Symbols + enrichment only (after graphify)
300
+ pmc bootstrap . --stage-b --enrich
301
+
302
+ # Custom model
303
+ OLLAMA_MODEL=qwen3-coder:30b pmc bootstrap . --all --enrich
304
+ ```
305
+
306
+ **Environment variables for bootstrap:**
307
+
308
+ | Variable | Default | Description |
309
+ |---|---|---|
310
+ | `OLLAMA_URL` | `http://localhost:11434` | Ollama REST endpoint |
311
+ | `OLLAMA_MODEL` | `deepseek-coder-v2:16b-ctx32k` | Ollama model |
312
+ | `PMC_CONCURRENCY` | `8` | Parallel slots for worklist |
313
+ | `PMC_GRAPHIFY_PATH` | *(auto-detect)* | Custom path to graphify executable |
314
+
315
+ ---
316
+
317
+ ### `pmc enrich` / `pmc enrich-queue`
318
+
319
+ Run or start the semantic enrichment queue.
320
+
321
+ ```bash
322
+ pmc enrich # One-shot enrichment
323
+ pmc enrich-queue # Continuous queue (long-running)
324
+ ```
325
+
326
+ The enrichment queue:
327
+ 1. Reads `worklist.json` for pending symbols
328
+ 2. For each symbol, extracts the source code fragment
329
+ 3. Calls the local Ollama LLM with a structured prompt
330
+ 4. Stores the result as a memory via `agent-memory-mcp`
331
+ 5. Updates `graph.json`, `symbol-index.json`, and `worklist.json`
332
+
333
+ **Internal pipeline per symbol:**
334
+ ```
335
+ Symbol → semantic-unit (code fragment + imports)
336
+ → local-model-provider (Ollama) → structured report
337
+ → normalize-semantic-report → memory payload
338
+ → agent-memory: store → memoryId
339
+ → finalize-enrichment (graph + index + worklist)
340
+ ```
73
341
 
74
- During workflow execution, artifacts accumulate under:
342
+ ---
75
343
 
76
- ```text
77
- .planning/project-memory-context/
78
- intake/
79
- graph/
80
- enrichment/
81
- runs/
344
+ ### `pmc context`
345
+
346
+ Render project context for the current directory or a specific target.
347
+
348
+ ```bash
349
+ pmc context [target] [--refresh] [--depth compact|extended|deep|disk]
82
350
  ```
83
351
 
84
- ## MCP servers
352
+ | Option | Description |
353
+ |---|---|
354
+ | `target` | Symbol key or file path to focus on (default: project overview) |
355
+ | `--refresh` | Re-detect files and refresh stale memories |
356
+ | `--depth` | Output verbosity (default: `compact`) |
357
+
358
+ Depth levels:
359
+ - **compact** — symbol name + one-line summary
360
+ - **extended** — full LLM-generated description
361
+ - **deep** — includes all neighbors (depends on / depended by)
362
+ - **disk** — includes raw source code
85
363
 
86
- The bootstrap flow writes `.mcp.json` with an `agent-memory` server that runs:
364
+ ---
365
+
366
+ ### `pmc status`
367
+
368
+ Show enrichment progress and system health.
87
369
 
88
370
  ```bash
89
- npx -y @aabadin/agent-memory-mcp
371
+ pmc status
90
372
  ```
91
373
 
92
- OpenCode plugin integration may also inject local MCP entries at runtime using values from `.planning/project-memory-context/install.json`:
374
+ Output:
375
+ ```
376
+ Enrichment config:
377
+ Preferred modes: local-model, cloud-api, agent-subagent
378
+ Local model: deepseek-coder-v2:16b-ctx32k @ http://localhost:11434
379
+
380
+ Worklist:
381
+ Total symbols: 314
382
+ Pending: 201
383
+ Enriched: 87
384
+ Stale: 21
385
+ Failed: 5
386
+ ```
93
387
 
94
- - `pmc-local-model`
95
- - `pmc-agent-memory`
388
+ ---
96
389
 
97
- `pmc-local-model` exposes a semantic report tool backed by Ollama.
390
+ ### `pmc doctor`
98
391
 
99
- `pmc-agent-memory` points at the public `agent-memory-mcp` binary when plugin injection is used.
392
+ Run environment diagnostics to check that all dependencies are available.
100
393
 
101
- ## Workflow order
394
+ ```bash
395
+ pmc doctor
396
+ ```
102
397
 
103
- 1. `stage-a`
104
- - intake
105
- - brainstorming clarification
106
- - graphify structural mapping
398
+ Checks:
399
+ - **node-version** — Node.js ≥ 18?
400
+ - **python** — Python 3 available?
401
+ - **graphifyy** graphifyy package installed?
402
+ - **ollama** — Ollama reachable?
403
+ - **memory-db-path** — MEMORY_DB_PATH set and writable?
404
+ - **embedding-cache** — EMBEDDING_CACHE_PATH configured?
107
405
 
108
- 2. `stage-b`
109
- - build worklist
110
- - prepare semantic jobs
111
- - call `pmc-local-model`
112
- - materialize `*.memory.json`
113
- - store/update in `pmc-agent-memory`
114
- - materialize `*.result.json`
115
- - finalize or fail each symbol
406
+ ---
116
407
 
117
- ## Development verification
408
+ ### `pmc init`
118
409
 
119
- Run the local test suite:
410
+ Initialize a fresh PMC project structure.
120
411
 
121
412
  ```bash
122
- node --test "tools/project-memory-context/tests/*.test.mjs"
413
+ pmc init <project-root>
123
414
  ```
415
+
416
+ Creates the `.planning/project-memory-context/` directory tree and default configuration files.
417
+
418
+ ---
419
+
420
+ ### `pmc new-project`
421
+
422
+ Delegates to `bootstrap.mjs`. Same as `pmc bootstrap`.
423
+
424
+ ```bash
425
+ pmc new-project <target-repo> [--all] [--stage-a] [--stage-b] [--enrich]
426
+ ```
427
+
428
+ ---
429
+
430
+ ### `pmc sanitize`
431
+
432
+ Clean up stale enrichment artifacts and rebuild worklist state.
433
+
434
+ ```bash
435
+ pmc sanitize
436
+ ```
437
+
438
+ ---
439
+
440
+ ### `pmc project-context`
441
+
442
+ Materialize or refresh the 9 base project-context memories.
443
+
444
+ ```bash
445
+ pmc project-context [--refresh]
446
+ ```
447
+
448
+ | Flag | Description |
449
+ |---|---|
450
+ | *(none)* | Generate all 9 memories from scratch |
451
+ | `--refresh` | Only refresh memories whose source files have changed |
452
+
453
+ ---
454
+
455
+ ## Environment Variables
456
+
457
+ ### PMC variables
458
+
459
+ | Variable | Default | Description |
460
+ |---|---|---|
461
+ | `PMC_CLOUD_API_KEY` | *(none)* | API key for cloud enrichment fallback |
462
+ | `PMC_CONCURRENCY` | `8` | Parallel enrichment slots |
463
+ | `PMC_GRAPHIFY_PATH` | *(auto-detect)* | Custom path to graphify executable |
464
+ | `PMC_GRAPHIFY_BIN` | *(auto-detect)* | Alternative to `PMC_GRAPHIFY_PATH` |
465
+ | `PMC_GLOBAL_CONFIG` | `~/.config/pmc` | Override global config directory |
466
+ | `PMC_LOCAL_MODEL_BASE_URL` | `http://localhost:11434` | Ollama URL for enrichment |
467
+ | `PMC_LOCAL_MODEL` | *(from setup)* | Ollama model for enrichment |
468
+
469
+ ### Agent Memory MCP variables
470
+
471
+ | Variable | Required | Description |
472
+ |---|---|---|
473
+ | `MEMORY_DB_PATH` | Yes | Path to LanceDB database directory |
474
+ | `EMBEDDING_MODEL` | No | `Xenova/bge-m3` (default) |
475
+ | `EMBEDDING_DIMENSIONS` | No | `1024` (inferred from model) |
476
+ | `EMBEDDING_POOLING` | No | `cls` (inferred from model) |
477
+ | `EMBEDDING_CACHE_PATH` | No | Content-addressed binary embedding cache |
478
+ | `MEMORY_DECAY_HALF_LIFE` | No | `30` days (set `0` to disable) |
479
+ | `ENABLE_HARDCOPY` | No | `true` to enable JSON file backup |
480
+ | `HARDCOPY_PATH` | If hardcopy | Directory for JSON mirror files |
481
+
482
+ ---
483
+
484
+ ## Project Structure
485
+
486
+ A project with PMC installed will have:
487
+
488
+ ```
489
+ your-repo/
490
+ ├── .planning/
491
+ │ └── project-memory-context/
492
+ │ ├── install.json # PMC install state
493
+ │ ├── enrichment/
494
+ │ │ ├── worklist.json # All symbols + enrichment status
495
+ │ │ ├── sync-manifest.json # Pending agent-memory syncs
496
+ │ │ ├── semantic-jobs.json # Prepared LLM enrichment jobs
497
+ │ │ ├── failures.json # Failed enrichment attempts
498
+ │ │ └── *.memory.json # Per-symbol memory payloads
499
+ │ ├── graph/
500
+ │ │ ├── graph.json # Knowledge graph (graphifyy output)
501
+ │ │ ├── graph.html # Visual knowledge graph
502
+ │ │ ├── graph.metadata.json # Graph metadata
503
+ │ │ └── GRAPH_REPORT.md # Human-readable graph report
504
+ │ ├── intake/ # Project description + goals
505
+ │ ├── runs/ # Run-specific artifacts
506
+ │ └── project-context/
507
+ │ ├── detected/ # Auto-detected context
508
+ │ ├── declared/ # User-declared context
509
+ │ ├── materialized/ # 9 base memories (JSON)
510
+ │ ├── markdown/ # Human-readable context
511
+ │ └── state/ # Refresh state tracking
512
+ ├── .opencode/opencode.json # OpenCode MCP config (if opencode)
513
+ ├── .claude/project-memory-context.json # Claude Code enrichment config
514
+ ├── .mcp.json # Universal MCP server config
515
+ ├── AGENTS.md # PMC autostart block
516
+ ├── project-memory-context.md # Command template
517
+ └── project-memory-context workflow.md # Workflow template
518
+ ```
519
+
520
+ ---
521
+
522
+ ## 9 Base Project-Context Memories
523
+
524
+ When you run `pmc project-context`, PMC generates and stores 9 memories in `agent-memory`:
525
+
526
+ | # | Memory Key | Description |
527
+ |---|---|---|
528
+ | 1 | `stack-runtime` | Language, framework, runtime version (from `package.json`, `tsconfig.json`, etc.) |
529
+ | 2 | `stack-dependencies` | Key dependencies and their purposes |
530
+ | 3 | `structure-topology` | Directory layout, module organization |
531
+ | 4 | `structure-entrypoints` | Main entry points and build targets |
532
+ | 5 | `architecture-overview` | High-level architectural patterns |
533
+ | 6 | `architecture-data-flow` | Data flow and state management |
534
+ | 7 | `technical-rules` | Code conventions, linting rules, config |
535
+ | 8 | `intake-goals` | User-declared project goals and focus areas |
536
+ | 9 | `intake-description` | Human-written project summary |
537
+
538
+ These are refreshed automatically when their source files change (`--refresh` mode).
539
+
540
+ ---
541
+
542
+ ## Credits
543
+
544
+ ### Agent Memory MCP
545
+
546
+ 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.
547
+
548
+ **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.
549
+
550
+ **Modifications for this project:**
551
+ - Published under `@aabadin` scope (original author did not publish to npm under `@brain` scope)
552
+ - Version bumped to 2.0.0
553
+ - All references updated from `@brain/` to `@aabadin/` scope
554
+ - Fully compatible with the original API and tool set
555
+
556
+ 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`.
557
+
558
+ ### Graphifyy
559
+
560
+ [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.
561
+
562
+ **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.
563
+
564
+ ---
565
+
566
+ ## License
567
+
568
+ GPL-3.0-or-later — see [LICENSE](LICENSE).