@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.
- package/.claude-plugin/marketplace.json +19 -0
- package/.cursor-plugin/marketplace.json +19 -0
- package/LICENSE +21 -0
- package/README.md +331 -0
- package/dist/cli/adapters.d.ts +32 -0
- package/dist/cli/adapters.d.ts.map +1 -0
- package/dist/cli/adapters.js +368 -0
- package/dist/cli/adapters.js.map +1 -0
- package/dist/cli/environment.d.ts +34 -0
- package/dist/cli/environment.d.ts.map +1 -0
- package/dist/cli/environment.js +119 -0
- package/dist/cli/environment.js.map +1 -0
- package/dist/cli/index.d.ts +3 -0
- package/dist/cli/index.d.ts.map +1 -0
- package/dist/cli/index.js +1108 -0
- package/dist/cli/index.js.map +1 -0
- package/dist/docs-schema.d.ts +27 -0
- package/dist/docs-schema.d.ts.map +1 -0
- package/dist/docs-schema.js +100 -0
- package/dist/docs-schema.js.map +1 -0
- package/dist/evals/index.d.ts +13 -0
- package/dist/evals/index.d.ts.map +1 -0
- package/dist/evals/index.js +205 -0
- package/dist/evals/index.js.map +1 -0
- package/dist/evals/performance-comparison.d.ts +23 -0
- package/dist/evals/performance-comparison.d.ts.map +1 -0
- package/dist/evals/performance-comparison.js +76 -0
- package/dist/evals/performance-comparison.js.map +1 -0
- package/dist/evals/platform-integration.d.ts +34 -0
- package/dist/evals/platform-integration.d.ts.map +1 -0
- package/dist/evals/platform-integration.js +186 -0
- package/dist/evals/platform-integration.js.map +1 -0
- package/dist/formatter/index.d.ts +15 -0
- package/dist/formatter/index.d.ts.map +1 -0
- package/dist/formatter/index.js +207 -0
- package/dist/formatter/index.js.map +1 -0
- package/dist/hybrid-search/index.d.ts +40 -0
- package/dist/hybrid-search/index.d.ts.map +1 -0
- package/dist/hybrid-search/index.js +277 -0
- package/dist/hybrid-search/index.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp-server/index.d.ts +6 -0
- package/dist/mcp-server/index.d.ts.map +1 -0
- package/dist/mcp-server/index.js +114 -0
- package/dist/mcp-server/index.js.map +1 -0
- package/dist/mcp-server/p0-parser.d.ts +43 -0
- package/dist/mcp-server/p0-parser.d.ts.map +1 -0
- package/dist/mcp-server/p0-parser.js +108 -0
- package/dist/mcp-server/p0-parser.js.map +1 -0
- package/dist/mcp-server/resources.d.ts +3 -0
- package/dist/mcp-server/resources.d.ts.map +1 -0
- package/dist/mcp-server/resources.js +156 -0
- package/dist/mcp-server/resources.js.map +1 -0
- package/dist/mcp-server/tools.d.ts +15 -0
- package/dist/mcp-server/tools.d.ts.map +1 -0
- package/dist/mcp-server/tools.js +928 -0
- package/dist/mcp-server/tools.js.map +1 -0
- package/dist/schema-constants.d.ts +7 -0
- package/dist/schema-constants.d.ts.map +1 -0
- package/dist/schema-constants.js +33 -0
- package/dist/schema-constants.js.map +1 -0
- package/package.json +84 -0
- package/plugins/adapters/claude-code/.claude-plugin/plugin.json +26 -0
- package/plugins/adapters/claude-code/CLAUDE.md +21 -0
- package/plugins/adapters/claude-code/README.md +37 -0
- package/plugins/adapters/claude-code/agents/governance-checker.md +27 -0
- package/plugins/adapters/claude-code/agents/memory-writer.md +31 -0
- package/plugins/adapters/claude-code/hooks/SessionStart.js +55 -0
- package/plugins/adapters/claude-code/hooks/hooks.json +52 -0
- package/plugins/adapters/generic/BOOTSTRAP_INSTRUCTION.md +30 -0
- package/plugins/adapters/generic/README.md +50 -0
- package/plugins/ai-memory/.claude-plugin/plugin.json +30 -0
- package/plugins/ai-memory/.cursor-plugin/plugin.json +18 -0
- package/plugins/ai-memory/.mcp.json +19 -0
- package/plugins/ai-memory/agents/governance-critic/AGENT.md +57 -0
- package/plugins/ai-memory/agents/memory-auditor/AGENT.md +54 -0
- package/plugins/ai-memory/rules/context7-tool-reference.md +16 -0
- package/plugins/ai-memory/rules/load-memory.md +22 -0
- package/plugins/ai-memory/rules/parallel-safe-planning.md +19 -0
- package/plugins/ai-memory/skills/mem-auto-review/SKILL.md +51 -0
- package/plugins/ai-memory/skills/mem-compound/SKILL.md +105 -0
- package/plugins/ai-memory/skills/mem-init/SKILL.md +48 -0
- package/plugins/ai-memory/skills/mem-session-close/SKILL.md +38 -0
- package/plugins/ai-memory/skills/mem-validate/SKILL.md +54 -0
- package/templates/.ai/IDENTITY.md +23 -0
- package/templates/.ai/agents/_base-auditor.md +28 -0
- package/templates/.ai/agents/_template.md +23 -0
- package/templates/.ai/memory/debugging.md +14 -0
- package/templates/.ai/memory/decisions.md +8 -0
- package/templates/.ai/memory/improvements.md +7 -0
- package/templates/.ai/memory/memory-index.md +9 -0
- package/templates/.ai/memory/patterns.md +8 -0
- package/templates/.ai/reference/PROJECT.md +5 -0
- package/templates/.ai/reference/capability-specs.json +31 -0
- package/templates/.ai/reference/environment-specs.json +41 -0
- package/templates/.ai/sessions/archive/thread-archive.md +15 -0
- package/templates/.ai/sessions/open-items.md +13 -0
- package/templates/.ai/toolbox/README.md +5 -0
- package/templates/.ai/toolbox/browser.md +30 -0
- package/templates/.ai/toolbox/integrations.md +44 -0
- package/templates/.ai/toolbox/shell.md +38 -0
- 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
|
+
[](https://github.com/radix-ai/ai-memory/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/@radix-ai/ai-memory)
|
|
5
|
+
[](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"}
|