@radix-ai/ai-memory 0.1.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.
Files changed (105) hide show
  1. package/.claude-plugin/marketplace.json +19 -0
  2. package/.cursor-plugin/marketplace.json +19 -0
  3. package/LICENSE +21 -0
  4. package/README.md +331 -0
  5. package/dist/cli/adapters.d.ts +32 -0
  6. package/dist/cli/adapters.d.ts.map +1 -0
  7. package/dist/cli/adapters.js +368 -0
  8. package/dist/cli/adapters.js.map +1 -0
  9. package/dist/cli/environment.d.ts +34 -0
  10. package/dist/cli/environment.d.ts.map +1 -0
  11. package/dist/cli/environment.js +119 -0
  12. package/dist/cli/environment.js.map +1 -0
  13. package/dist/cli/index.d.ts +3 -0
  14. package/dist/cli/index.d.ts.map +1 -0
  15. package/dist/cli/index.js +1108 -0
  16. package/dist/cli/index.js.map +1 -0
  17. package/dist/docs-schema.d.ts +27 -0
  18. package/dist/docs-schema.d.ts.map +1 -0
  19. package/dist/docs-schema.js +100 -0
  20. package/dist/docs-schema.js.map +1 -0
  21. package/dist/evals/index.d.ts +13 -0
  22. package/dist/evals/index.d.ts.map +1 -0
  23. package/dist/evals/index.js +205 -0
  24. package/dist/evals/index.js.map +1 -0
  25. package/dist/evals/performance-comparison.d.ts +23 -0
  26. package/dist/evals/performance-comparison.d.ts.map +1 -0
  27. package/dist/evals/performance-comparison.js +76 -0
  28. package/dist/evals/performance-comparison.js.map +1 -0
  29. package/dist/evals/platform-integration.d.ts +34 -0
  30. package/dist/evals/platform-integration.d.ts.map +1 -0
  31. package/dist/evals/platform-integration.js +186 -0
  32. package/dist/evals/platform-integration.js.map +1 -0
  33. package/dist/formatter/index.d.ts +15 -0
  34. package/dist/formatter/index.d.ts.map +1 -0
  35. package/dist/formatter/index.js +207 -0
  36. package/dist/formatter/index.js.map +1 -0
  37. package/dist/hybrid-search/index.d.ts +40 -0
  38. package/dist/hybrid-search/index.d.ts.map +1 -0
  39. package/dist/hybrid-search/index.js +277 -0
  40. package/dist/hybrid-search/index.js.map +1 -0
  41. package/dist/index.d.ts +4 -0
  42. package/dist/index.d.ts.map +1 -0
  43. package/dist/index.js +5 -0
  44. package/dist/index.js.map +1 -0
  45. package/dist/mcp-server/index.d.ts +6 -0
  46. package/dist/mcp-server/index.d.ts.map +1 -0
  47. package/dist/mcp-server/index.js +114 -0
  48. package/dist/mcp-server/index.js.map +1 -0
  49. package/dist/mcp-server/p0-parser.d.ts +43 -0
  50. package/dist/mcp-server/p0-parser.d.ts.map +1 -0
  51. package/dist/mcp-server/p0-parser.js +108 -0
  52. package/dist/mcp-server/p0-parser.js.map +1 -0
  53. package/dist/mcp-server/resources.d.ts +3 -0
  54. package/dist/mcp-server/resources.d.ts.map +1 -0
  55. package/dist/mcp-server/resources.js +156 -0
  56. package/dist/mcp-server/resources.js.map +1 -0
  57. package/dist/mcp-server/tools.d.ts +15 -0
  58. package/dist/mcp-server/tools.d.ts.map +1 -0
  59. package/dist/mcp-server/tools.js +928 -0
  60. package/dist/mcp-server/tools.js.map +1 -0
  61. package/dist/schema-constants.d.ts +7 -0
  62. package/dist/schema-constants.d.ts.map +1 -0
  63. package/dist/schema-constants.js +33 -0
  64. package/dist/schema-constants.js.map +1 -0
  65. package/package.json +84 -0
  66. package/plugins/adapters/claude-code/.claude-plugin/plugin.json +26 -0
  67. package/plugins/adapters/claude-code/CLAUDE.md +21 -0
  68. package/plugins/adapters/claude-code/README.md +37 -0
  69. package/plugins/adapters/claude-code/agents/governance-checker.md +27 -0
  70. package/plugins/adapters/claude-code/agents/memory-writer.md +31 -0
  71. package/plugins/adapters/claude-code/hooks/SessionStart.js +55 -0
  72. package/plugins/adapters/claude-code/hooks/hooks.json +52 -0
  73. package/plugins/adapters/generic/BOOTSTRAP_INSTRUCTION.md +30 -0
  74. package/plugins/adapters/generic/README.md +50 -0
  75. package/plugins/ai-memory/.claude-plugin/plugin.json +30 -0
  76. package/plugins/ai-memory/.cursor-plugin/plugin.json +18 -0
  77. package/plugins/ai-memory/.mcp.json +19 -0
  78. package/plugins/ai-memory/agents/governance-critic/AGENT.md +57 -0
  79. package/plugins/ai-memory/agents/memory-auditor/AGENT.md +54 -0
  80. package/plugins/ai-memory/rules/context7-tool-reference.md +16 -0
  81. package/plugins/ai-memory/rules/load-memory.md +22 -0
  82. package/plugins/ai-memory/rules/parallel-safe-planning.md +19 -0
  83. package/plugins/ai-memory/skills/mem-auto-review/SKILL.md +51 -0
  84. package/plugins/ai-memory/skills/mem-compound/SKILL.md +105 -0
  85. package/plugins/ai-memory/skills/mem-init/SKILL.md +48 -0
  86. package/plugins/ai-memory/skills/mem-session-close/SKILL.md +38 -0
  87. package/plugins/ai-memory/skills/mem-validate/SKILL.md +54 -0
  88. package/templates/.ai/IDENTITY.md +23 -0
  89. package/templates/.ai/agents/_base-auditor.md +28 -0
  90. package/templates/.ai/agents/_template.md +23 -0
  91. package/templates/.ai/memory/debugging.md +14 -0
  92. package/templates/.ai/memory/decisions.md +8 -0
  93. package/templates/.ai/memory/improvements.md +7 -0
  94. package/templates/.ai/memory/memory-index.md +9 -0
  95. package/templates/.ai/memory/patterns.md +8 -0
  96. package/templates/.ai/reference/PROJECT.md +5 -0
  97. package/templates/.ai/reference/capability-specs.json +31 -0
  98. package/templates/.ai/reference/environment-specs.json +41 -0
  99. package/templates/.ai/sessions/archive/thread-archive.md +15 -0
  100. package/templates/.ai/sessions/open-items.md +13 -0
  101. package/templates/.ai/toolbox/README.md +5 -0
  102. package/templates/.ai/toolbox/browser.md +30 -0
  103. package/templates/.ai/toolbox/integrations.md +44 -0
  104. package/templates/.ai/toolbox/shell.md +38 -0
  105. package/templates/AGENTS.md +4 -0
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "ai-memory",
3
+ "owner": {
4
+ "name": "radix-ai",
5
+ "url": "https://github.com/radix-ai/ai-memory"
6
+ },
7
+ "metadata": {
8
+ "description": "Persistent AI memory for any project. Multi-agent collaboration, RALPH loops, governance enforcement.",
9
+ "version": "0.1.0",
10
+ "pluginRoot": "plugins"
11
+ },
12
+ "plugins": [
13
+ {
14
+ "name": "ai-memory",
15
+ "source": "ai-memory",
16
+ "description": "Persistent project memory. Compound protocol, multi-agent claims, session sync. 5 skills, 2 agents, 2 rules, 12 MCP tools."
17
+ }
18
+ ]
19
+ }
@@ -0,0 +1,19 @@
1
+ {
2
+ "name": "ai-memory",
3
+ "owner": {
4
+ "name": "radix-ai",
5
+ "url": "https://github.com/radix-ai/ai-memory"
6
+ },
7
+ "metadata": {
8
+ "description": "Persistent AI memory for any project. Compound protocol, governance enforcement, MCP server.",
9
+ "version": "0.1.0",
10
+ "pluginRoot": "plugins"
11
+ },
12
+ "plugins": [
13
+ {
14
+ "name": "ai-memory",
15
+ "source": "ai-memory",
16
+ "description": "Persistent project memory with multi-agent collaboration. 5 skills, 2 agents, 2 rules, 12 MCP tools."
17
+ }
18
+ ]
19
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Radix AI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,331 @@
1
+ # ai-memory
2
+
3
+ [![CI](https://github.com/radix-ai/ai-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/radix-ai/ai-memory/actions/workflows/ci.yml)
4
+ [![npm](https://img.shields.io/npm/v/@radix-ai/ai-memory)](https://www.npmjs.com/package/@radix-ai/ai-memory)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ Persistent AI memory for any project. Drop a `.ai/` directory into any codebase — Claude Code, Cursor, Windsurf, or any other AI tool reads it at session start and carries knowledge forward.
8
+
9
+ ```
10
+ npm install @radix-ai/ai-memory
11
+ npx @radix-ai/ai-memory init
12
+ ```
13
+
14
+ ---
15
+
16
+ ## The problem
17
+
18
+ AI coding assistants forget everything between sessions. Decisions made last week, bugs already fixed, patterns that work — gone on every restart. You re-explain the stack, re-discover the same issues, watch the AI repeat the same mistakes.
19
+
20
+ ## What this does
21
+
22
+ `ai-memory` gives any AI tool persistent memory by maintaining a structured `.ai/` directory in your project. The AI reads it at session start. A local MCP server gives it structured tools to search and write memory. A governance layer enforces project rules in code, not prompts.
23
+
24
+ ---
25
+
26
+ ## Install
27
+
28
+ The install command sets up three things: **context loading** (the AI reads `.ai/` at session start), **MCP server** (structured memory tools), and **skills** (slash commands like `/mem-compound`).
29
+
30
+ | Tool | Install | Skills |
31
+ |---|---|---|
32
+ | **Cursor** | `/add-plugin ai-memory` | `/mem-compound`, `/mem-session-close`, `/mem-validate`, `/mem-init` |
33
+ | **Claude Code** | `/plugin install ai-memory` | Same slash commands via plugin |
34
+ | **Windsurf** | `npx @radix-ai/ai-memory install --to windsurf` | Ask AI: "run the compound protocol" |
35
+ | **VS Code + Cline** | `npx @radix-ai/ai-memory install --to cline` | Ask AI: "run the compound protocol" |
36
+ | **VS Code + Copilot** | `npx @radix-ai/ai-memory install --to copilot` | Paste SKILL.md content into chat |
37
+ | **Any other tool** | Paste bootstrap instruction into system prompt | Paste SKILL.md content |
38
+
39
+ ### CLI only
40
+ ```bash
41
+ npx @radix-ai/ai-memory init # scaffold .ai/
42
+ npx @radix-ai/ai-memory install --to cursor # install for your tool
43
+ ```
44
+
45
+ ---
46
+
47
+ ## Quick start
48
+
49
+ `install` runs `init` automatically if `.ai/` is missing, so you can run either order.
50
+
51
+ ```bash
52
+ # 1. Install for your tool (scaffolds .ai/ if needed)
53
+ npx @radix-ai/ai-memory install --to cursor # or claude-code, windsurf, cline, copilot
54
+
55
+ # 2. Fill in what your project is
56
+ # Edit .ai/IDENTITY.md and .ai/PROJECT_STATUS.md (project status)
57
+
58
+ # 3. Restart your AI tool (or start a new chat)
59
+
60
+ # 4. At the end of a session with real learning:
61
+ /mem-compound
62
+ ```
63
+
64
+ Or run `init` first to scaffold `.ai/` before installing.
65
+
66
+ ### Verify
67
+
68
+ ```bash
69
+ npx @radix-ai/ai-memory verify
70
+ ```
71
+
72
+ Checks: `.ai/` structure, bootstrap installed, MCP configured, harness validity, rule coverage, memory index populated.
73
+
74
+ Or manually in a session: ask *"Call search_memory with query 'test'"* (confirms MCP). Then *"What does .ai/IDENTITY.md say?"* (confirms context loading).
75
+
76
+ ### Troubleshooting
77
+
78
+ | Issue | What to do |
79
+ |-------|------------|
80
+ | `'ai-memory' is not recognized` | You're in the ai-memory dev repo. Run `npm run build` then `node dist/cli/index.js init` and `node dist/cli/index.js install --to cursor`. For published users, use `npx @radix-ai/ai-memory` — the package is pre-built. |
81
+ | MCP tools not available | `install` scaffolds `.ai/` if missing. Restart Cursor (or start a new chat) after install. |
82
+ | Cursor not picking up MCP | Cursor reads `.cursor/mcp.json`. The install writes it for Cursor. If you added manually, ensure the config is in `.cursor/mcp.json` (not `.mcp.json` at project root). |
83
+ | `Cannot find module '.ai/mcp-launcher.cjs'` | Run `npx @radix-ai/ai-memory install --to cursor` first — it creates `.ai/` and the launcher. |
84
+ | `'ai-memory' is not recognized` (Windows) | The launcher uses `cmd /c` on Windows. If it still fails, delete `.cursor/mcp.json` and run `install --to cursor` again to refresh the launcher. |
85
+
86
+ ---
87
+
88
+ ## What gets created
89
+
90
+ ```
91
+ .ai/
92
+ ├── IDENTITY.md — What this project is; constraints for the AI
93
+ ├── PROJECT_STATUS.md — Current focus, open questions, what's working
94
+ ├── memory/
95
+ │ ├── decisions.md — Architectural decisions [P0/P1/P2 tagged]
96
+ │ ├── patterns.md — Reusable patterns and anti-patterns
97
+ │ ├── debugging.md — Non-obvious bugs with root cause and fix
98
+ │ ├── improvements.md — Incremental improvements over time
99
+ │ └── memory-index.md — Auto-generated priority index
100
+ ├── agents/ — Agent methodology files
101
+ ├── skills/ — Project domain knowledge
102
+ ├── toolbox/ — General tech knowledge
103
+ ├── rules/ — Behavioral constraints
104
+ ├── sessions/
105
+ │ ├── open-items.md — Live registry of open tasks
106
+ │ └── archive/
107
+ │ └── thread-archive.md
108
+ └── reference/
109
+ └── PROJECT.md — Architecture (loaded on demand only)
110
+ ```
111
+
112
+ Add governance, evals, docs schema, and ACP with `--full`:
113
+ ```bash
114
+ npx @radix-ai/ai-memory init --full
115
+ ```
116
+ Creates: `acp/`, `docs-schema.json`, `rules/doc-placement.md`, `agents/docs-manager.md`.
117
+
118
+ ---
119
+
120
+ ## Skills
121
+
122
+ | Skill | When to use |
123
+ |---|---|
124
+ | `/mem-compound` | End of any session with real learning |
125
+ | `/mem-session-close` | End of a short/exploratory session |
126
+ | `/mem-init` | First-time project setup |
127
+ | `/mem-validate` | Before a risky change (Full tier) |
128
+ | `/mem-auto-review` | Automated PR review (Bugbot, CI, automations) |
129
+
130
+ ### Project-specific compound
131
+
132
+ `/mem-compound` runs standard steps (scan, conflict check, update status, archive, sync) plus project-specific doc updates. The skill maps session work to domains (UI, Backend/API, AI/ML, Architecture, Backlog) and updates docs via `get_doc_path` and `validate_doc_placement`. Open items may be broad or categorical. Work done anywhere must be broken down into atomic tasks that fit RALPH loops and avoid conflicts when agents work in parallel. With `init --full`, `.ai/docs-schema.json` defines canonical paths and naming (SCREAMING_SNAKE by default).
133
+
134
+ ---
135
+
136
+ ## CLI
137
+
138
+ ```bash
139
+ ai-memory init [--full] [--download-model] # Scaffold .ai/. Use --download-model to pre-fetch hybrid search model (~23MB).
140
+ ai-memory install --to <tool> # Bootstrap for cursor, windsurf, cline, copilot, claude-code
141
+ ai-memory mcp # Start MCP server (stdio)
142
+ ai-memory mcp --http --port 3100 # Start MCP server (HTTP, for cloud agents)
143
+ ai-memory validate # Validate all .ai/ files
144
+ ai-memory validate-docs # Validate doc placement against .ai/docs-schema.json (staged or --paths)
145
+ # Pre-commit: add `ai-memory validate-docs` to validate new docs before commit (e.g. via husky)
146
+ ai-memory index # Regenerate memory-index.md from memory files
147
+ ai-memory fmt # Auto-format YAML frontmatter
148
+ ai-memory eval [--json] # Memory health report
149
+ ai-memory prune [--dry-run] # Review stale entries
150
+ ai-memory generate-harness # Compile rule set from [P0] entries
151
+ ai-memory verify [--json] # Verify full installation chain (.ai/, bootstrap, MCP, harness)
152
+
153
+ # Extensibility
154
+ ai-memory agent create <name> # Scaffold a new agent
155
+ ai-memory skill create <name> # Scaffold a new skill
156
+ ai-memory rule create <name> # Scaffold a new rule
157
+ ai-memory eval add <name> # Add a custom eval metric
158
+ ```
159
+
160
+ ---
161
+
162
+ ## Configuration
163
+
164
+ | Env var | Default | Description |
165
+ |---------|---------|-------------|
166
+ | `AI_DIR` | `./.ai` | Path to the `.ai/` directory |
167
+ | `AI_SEARCH` | `hybrid` | Search mode: `keyword` (TF only, no model), `semantic` (vector only), or `hybrid` (keyword + semantic + RRF). Use `keyword` for faster startup or constrained environments. |
168
+ | `AI_SEARCH_WASM` | — | Set to `1` to prefer WASM backend (onnxruntime-web) over native. Use on Windows when onnxruntime-node fails. Slower but cross-platform. |
169
+ | `AI_MODEL_PATH` | — | Local path to the embedding model for air-gapped/CI. When set, disables remote model downloads. Model must be in HuggingFace format under this path. |
170
+
171
+ **Platform note:** Semantic/hybrid search uses onnxruntime-node on Linux/macOS. On Windows, onnxruntime-node may be unavailable; set `AI_SEARCH=keyword` for keyword-only, or `AI_SEARCH_WASM=1` to try WASM.
172
+
173
+ ---
174
+
175
+ ## Governance (Full tier)
176
+
177
+ Tag decisions `[P0]` and add a `constraint_pattern` to enforce them in code:
178
+
179
+ ```markdown
180
+ ### [P0] No external auth libraries
181
+
182
+ **Context:** ...
183
+ **Decision:** Use the internal auth module only.
184
+
185
+ \`\`\`yaml
186
+ constraint_pattern:
187
+ type: ast
188
+ language: typescript
189
+ pattern: "import $_ from '$LIB'"
190
+ where:
191
+ LIB:
192
+ regex: "passport|jsonwebtoken|bcrypt"
193
+ path: "src/**/*.ts"
194
+ \`\`\`
195
+ ```
196
+
197
+ Then:
198
+ ```bash
199
+ ai-memory generate-harness # Compile .ai/temp/harness.json
200
+ ```
201
+
202
+ `validate_context` in `/mem-compound` will hard-block any commit that violates a [P0] rule.
203
+
204
+ ### Harness features
205
+
206
+ - **Path filtering:** Rules apply only to files matching `path` (minimatch glob). Example: `path: "src/**/*.ts"` skips `tests/`.
207
+ - **AST constraints:** Use `where` to filter by meta-variable regex (e.g. path traversal checks).
208
+ - **Deletion-aware regex:** Set `scope: "deletions"` to catch removal of protected content (e.g. `[P0]` markers).
209
+ - **Stability Certificate:** On success, returns an audit log of rules checked; on failure, a detailed violation report.
210
+
211
+ ---
212
+
213
+ ## Multi-agent & iterative loops
214
+
215
+ ### RALPH loops (iterative self-improvement)
216
+
217
+ PROJECT_STATUS.md is writable by default (`writable: true` in frontmatter). This means:
218
+ 1. Agent reads PROJECT_STATUS.md, picks a task, does work
219
+ 2. Agent updates PROJECT_STATUS.md with what it learned
220
+ 3. Agent exits (or session ends)
221
+ 4. Next iteration reads the updated PROJECT_STATUS.md
222
+ 5. Natural convergence through iteration
223
+
224
+ This follows the [autoresearch](https://github.com/mutable-state-inc/autoresearch-at-home) pattern and the [Ralph Wiggum](https://ralph-wiggum.ai/) approach: **the plan file on disk is the shared state.**
225
+
226
+ ### Concurrent agents (cloud agents, worktrees, background tasks)
227
+
228
+ `commit_memory` uses claim-based locking:
229
+ - Before writing, the agent acquires a claim on the target path
230
+ - If another agent holds an active claim (5-minute TTL), the write is rejected
231
+ - Claims auto-expire, so crashed agents don't permanently lock files
232
+ - Each write includes a `session_id` header for traceability
233
+
234
+ This works in:
235
+ - **Cursor Cloud Agents**: `.ai/` is in the git clone, MCP server starts per-agent
236
+ - **Claude Code worktrees**: `.ai/` is copied to the worktree; run `/mem-compound` before exit to persist
237
+ - **Claude Code sandbox**: MCP runs outside sandbox boundary — all memory tools work
238
+
239
+ ### Immutability model
240
+
241
+ | File | Default | Control |
242
+ |---|---|---|
243
+ | `IDENTITY.md` | Immutable | Set `writable: true` in frontmatter to allow AI writes |
244
+ | `PROJECT_STATUS.md` | Writable | Set `writable: false` in frontmatter to lock |
245
+ | `toolbox/`, `acp/`, `rules/` | Always immutable | Structural — no override |
246
+ | Everything else | Writable | Via `commit_memory` tool |
247
+
248
+ ---
249
+
250
+ ## MCP server
251
+
252
+ The MCP server starts automatically via `.mcp.json`. Tools exposed:
253
+
254
+ | Tool | What it does |
255
+ |---|---|
256
+ | `search_memory` | Hybrid search across `.ai/` (keyword + semantic + RRF). Params: `limit`, `include_deprecated` |
257
+ | `get_memory` | Summary of a specific topic |
258
+ | `commit_memory` | Write to `.ai/` with immutability + claim-based locking |
259
+ | `get_open_items` | Return open-items.md |
260
+ | `prune_memory` | Identify stale entries |
261
+ | `get_repo_root` | Git repo root path (for path resolution when agent runs from subdir) |
262
+ | `validate_context` | Check git diff against [P0] rules; returns Stability Certificate or violation report |
263
+ | `validate_schema` | Validate memory entry frontmatter |
264
+ | `generate_harness` | Compile `harness.json` from [P0] entries |
265
+ | `get_evals` | Return latest eval report |
266
+ | `claim_task` | Claim a task to prevent duplicate work across agents |
267
+ | `publish_result` | Publish task result (success/failure) to archive |
268
+ | `sync_memory` | Git commit `.ai/` changes (essential for ephemeral environments) |
269
+ | `get_doc_path` | Resolve canonical path for a doc type (use before creating docs) |
270
+ | `validate_doc_placement` | Validate doc path against `.ai/docs-schema.json` |
271
+ | `list_doc_types` | List doc types with path and pattern |
272
+
273
+ ### HTTP transport (for cloud agents)
274
+
275
+ ```bash
276
+ AI_MEMORY_AUTH_TOKEN=secret ai-memory mcp --http --port 3100
277
+ ```
278
+
279
+ | Env var | Purpose |
280
+ |---|---|
281
+ | `AI_MEMORY_AUTH_TOKEN` | Bearer token for HTTP auth (optional, no auth when unset) |
282
+ | `AI_MEMORY_CORS_ORIGINS` | Allowed origins, comma-separated (default: `*`) |
283
+
284
+ ### Context7 MCP (bundled)
285
+
286
+ `.mcp.json` includes the [Context7](https://context7.com) MCP server for up-to-date docs (Cursor, Claude Code, Windsurf, etc.). Works without an API key; set `CONTEXT7_API_KEY` for higher rate limits.
287
+
288
+ ---
289
+
290
+ ## Evals
291
+
292
+ ```bash
293
+ ai-memory eval
294
+ ```
295
+
296
+ Reports: rule coverage, session cadence, frontmatter coverage, open items, deprecated ratio, memory depth, session count, memory freshness, hook coverage, skill discoverability, cloud readiness, automation readiness, integration coverage.
297
+
298
+ Add custom metrics:
299
+ ```bash
300
+ ai-memory eval add my-metric
301
+ # Edit .ai/temp/custom-evals/my-metric.ts
302
+ ```
303
+
304
+ ---
305
+
306
+ ## ACP (Full tier)
307
+
308
+ `.ai/acp/manifest.json` declares this agent's capabilities to ACP-aware orchestrators like [`acpx`](https://github.com/openclaw/acpx). The MCP server is the transport layer; ACP is the identity layer.
309
+
310
+ ---
311
+
312
+ ## Design
313
+
314
+ - [Environment adaptation plan](docs/design/environment-adaptation-plan.md) — Spec-driven detection and injection for Cursor, VS Code, Claude Code, etc. (plan, not yet implemented)
315
+
316
+ ---
317
+
318
+ ## Related
319
+
320
+ - [acpx](https://github.com/openclaw/acpx) — Headless CLI for Agent Communication Protocol
321
+ - [Agent Communication Protocol](https://agentclientprotocol.com)
322
+ - [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) — Plugin this system is modeled after
323
+ - [lossless-claw](https://github.com/Martian-Engineering/lossless-claw) — Lossless context compaction (inspiration for session archive design)
324
+ - [autoresearch-at-home](https://github.com/mutable-state-inc/autoresearch-at-home) — Multi-agent iterative research
325
+ - [Ralph Wiggum](https://ralph-wiggum.ai/) — Iterative agent loops via plan file on disk
326
+
327
+ ---
328
+
329
+ ## License
330
+
331
+ MIT
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Tool adapter definitions for `ai-memory install --to <tool>`.
3
+ * Extracted from index.ts for maintainability.
4
+ */
5
+ export declare const BOOTSTRAP_INSTRUCTION = "## ai-memory \u2014 Project Memory\n\nThis project has persistent AI memory in `.ai/`.\n\n- **IDENTITY.md** \u2014 project constraints and behavioral rules\n- **PROJECT_STATUS.md** \u2014 current focus, open questions, what to try next (writable)\n- **memory/** \u2014 decisions, patterns, debugging history\n- **skills/** \u2014 domain-specific patterns and session protocols\n\nUse `search_memory` (MCP) to find relevant context before starting a task.\nUse `commit_memory` to write new entries \u2014 never edit memory files directly.\nIf MCP is not connected, read `.ai/memory/memory-index.md` for a summary and write to `.ai/memory/` files directly.\n\n`.ai/` is the canonical memory for this project. Save all project learnings here, not in your tool's built-in memory (e.g. ~/.claude/, Cursor memory, etc.). Tool-native memory is for user preferences only.\n\nImmutable paths (do not write): IDENTITY.md, toolbox/, acp/, rules/.\n\nAt the end of a meaningful session, run /mem-compound to capture learnings.\n";
6
+ /**
7
+ * Platform-agnostic MCP launcher. Detects OS at runtime and spawns correctly.
8
+ * - In ai-memory repo: run local dist directly (avoids npx entirely).
9
+ * - Windows: npx.cmd fails under spawn; npx-cli.js via node works.
10
+ * - macOS/Linux/BSD: npx works directly.
11
+ */
12
+ export declare const MCP_LAUNCHER = "#!/usr/bin/env node\nconst { spawn } = require(\"child_process\");\nconst path = require(\"path\");\nconst fs = require(\"fs\");\nconst platform = process.platform;\nconst opts = { stdio: \"inherit\", env: process.env };\n\n// Prefer local build when in ai-memory repo (avoids npx on Windows)\nconst cwd = process.cwd();\nconst localCli = path.join(cwd, \"dist\", \"cli\", \"index.js\");\nconst localMcp = path.join(cwd, \"dist\", \"mcp-server\", \"index.js\");\n\nlet child;\nif (fs.existsSync(localCli)) {\n child = spawn(\"node\", [localCli, \"mcp\"], opts);\n} else if (fs.existsSync(localMcp)) {\n child = spawn(\"node\", [localMcp], opts);\n} else if (platform === \"win32\") {\n const nodeDir = path.dirname(process.execPath);\n const npxCli = path.join(nodeDir, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\");\n if (fs.existsSync(npxCli)) {\n child = spawn(\"node\", [npxCli, \"@radix-ai/ai-memory\", \"mcp\"], opts);\n } else {\n child = spawn(\"cmd\", [\"/c\", \"npx\", \"@radix-ai/ai-memory\", \"mcp\"], { ...opts, windowsHide: true });\n }\n} else {\n child = spawn(\"npx\", [\"@radix-ai/ai-memory\", \"mcp\"], opts);\n}\n\nchild.on(\"error\", (err) => {\n console.error(\"[ai-memory-mcp] spawn failed:\", err.message);\n process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n process.exit(code ?? (signal ? 1 : 0));\n});\n";
13
+ /** MCP config path for the launcher (relative to project root). */
14
+ export declare const MCP_LAUNCHER_PATH = ".ai/mcp-launcher.cjs";
15
+ /** Single MCP config for all platforms. Uses launcher that detects OS at runtime. */
16
+ export declare function getMCPJson(): string;
17
+ /** Full skill content — written to .ai/skills/<name>/SKILL.md by install */
18
+ export declare const CANONICAL_SKILLS: Record<string, string>;
19
+ export declare const SESSION_START_HOOK = "#!/usr/bin/env node\n/**\n * ai-memory \u2014 Claude Code SessionStart hook\n * Injects minimal .ai/ context at session start (lazy loading).\n * Full context available via search_memory MCP tool.\n */\nconst { readFileSync, existsSync } = require(\"fs\");\nconst { join } = require(\"path\");\n\nconst aiDir = process.env.AI_DIR || join(process.cwd(), \".ai\");\n\nfunction safeRead(filePath, maxLines) {\n try {\n const content = readFileSync(filePath, \"utf-8\");\n if (maxLines) return content.split(\"\\n\").slice(0, maxLines).join(\"\\n\");\n return content;\n } catch { return \"\"; }\n}\n\nif (!existsSync(aiDir)) process.exit(0);\n\nconst sections = [];\n\nconst identity = safeRead(join(aiDir, \"IDENTITY.md\"));\nif (identity) sections.push(identity.trim());\n\nconst status = safeRead(join(aiDir, \"PROJECT_STATUS.md\"));\nif (status) sections.push(status.trim());\n\nconst index = safeRead(join(aiDir, \"memory/memory-index.md\"));\nif (index && !index.includes(\"<!-- Index will be generated\")) {\n sections.push(\"## Memory Index (priority-ranked)\\n\\n\" + index.trim());\n}\n\nif (sections.length === 0) process.exit(0);\n\nprocess.stdout.write(JSON.stringify({\n type: \"context\",\n content: sections.join(\"\\n\\n---\\n\\n\"),\n}));\n";
20
+ export declare const PRE_COMPACT_HOOK = "#!/usr/bin/env node\nconst fs = require(\"fs\");\nconst path = require(\"path\");\nconst aiDir = process.env.AI_DIR || path.join(process.cwd(), \".ai\");\nif (!fs.existsSync(aiDir)) process.exit(0);\nconst tempDir = path.join(aiDir, \"temp\");\nfs.mkdirSync(tempDir, { recursive: true });\nconst dump = { timestamp: new Date().toISOString(), event: \"pre-compact\" };\nfor (const f of [\"PROJECT_STATUS.md\", \"memory/memory-index.md\", \"sessions/open-items.md\"]) {\n const fp = path.join(aiDir, f);\n if (fs.existsSync(fp)) dump[f] = fs.readFileSync(fp, \"utf-8\").slice(0, 2000);\n}\nfs.writeFileSync(path.join(tempDir, \"pre-compact-dump.json\"), JSON.stringify(dump, null, 2));\n";
21
+ export declare const CLAUDE_HOOKS_CONFIG: string;
22
+ export interface ToolAdapter {
23
+ dest: string;
24
+ content: string;
25
+ mcp: boolean;
26
+ /** MCP config path (default: .mcp.json). Cursor uses .cursor/mcp.json */
27
+ mcpPath?: string;
28
+ /** Additional files to write (path relative to project root → content) */
29
+ extraFiles?: Record<string, string>;
30
+ }
31
+ export declare const TOOL_ADAPTERS: Record<string, ToolAdapter>;
32
+ //# sourceMappingURL=adapters.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/cli/adapters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,qBAAqB,6/BAkBjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,21CAoCxB,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AAExD,qFAAqF;AACrF,wBAAgB,UAAU,IAAI,MAAM,CAoBnC;AAQD,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsJnD,CAAC;AAIF,eAAO,MAAM,kBAAkB,0vCAwC9B,CAAC;AAGF,eAAO,MAAM,gBAAgB,orBAa5B,CAAC;AAEF,eAAO,MAAM,mBAAmB,QAiBrB,CAAC;AAIZ,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,OAAO,CAAC;IACb,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAiDrD,CAAC"}