aide-memory 0.5.18 → 0.6.1
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 +163 -86
- package/dist/cli/aide-memory.js +108 -94
- package/dist/memory/cli.js +83 -69
- package/dist/memory/index.js +89 -75
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,129 +1,155 @@
|
|
|
1
1
|
# aide-memory
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
> **Website:** https://aide-memory.dev
|
|
4
|
+
> **Docs:** https://aide-memory.dev/docs
|
|
5
|
+
> **Install:** `npm install -g aide-memory && aide-memory init`
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
## TL;DR
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
aide-memory is an auto-captured, auto-recalled, path-scoped memory layer for AI coding agents. It runs locally, plugs into Claude Code and Cursor via hooks + an MCP server, and uses git for team sync. It sits alongside `CLAUDE.md` and `.cursorrules`, not above or below; those cover always-on guidance, aide-memory covers the dynamic, area-specific knowledge that should only surface when it's relevant.
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
What this means in practice: when the agent opens a file in a code area you've taught aide-memory about, it gets prompted to recall what's been learned there. When you correct it or surface a non-obvious finding, hooks prompt it to remember. Memories live as JSON files in `.aide/memories/`, so `git add` / `git push` / `git pull` is the team-sync path. Personal preferences stay gitignored; team-shared memories travel with the repo.
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
Coding with agents has made developers significantly more productive. But it's created a new kind of friction.
|
|
16
|
-
|
|
17
|
-
You explain how the feature you're building ties into the rest of the system, the way you like to structure your code, the patterns to follow in this area. The agent gets it. You ship great work together. Next session, it's a blank slate. You re-explain the same things.
|
|
18
|
-
|
|
19
|
-
Critical decisions being made during conversations aren't being captured. Preferences, corrections, area knowledge, guidelines. So much valuable context doesn't persist, doesn't flow to the next session, to a different tool, or to a teammate's agent when they pick up work in the same area.
|
|
20
|
-
|
|
21
|
-
Rules files (CLAUDE.md, .cursorrules) help, but they have real limits:
|
|
22
|
-
|
|
23
|
-
- **No unified convention or structure.** A team guideline, a personal preference, an area decision, and a stack fact all blur into one file. The whole file gets injected on every turn, even when most of it might not be relevant to the area the agent is working in.
|
|
24
|
-
- **Corrections don't make it back.** What you teach the agent in conversation doesn't make it back into the rules file on its own.
|
|
25
|
-
- **Tool-specific.** What you teach your agent in Claude Code doesn't carry to Cursor unless you copy the file over manually.
|
|
26
|
-
- **Unscoped recall.** The whole file lands in context, or nothing does. There's no prompt for the agent to pull a relevant subset based on the file it just opened.
|
|
13
|
+
```bash
|
|
14
|
+
npm install -g aide-memory && aide-memory init
|
|
15
|
+
```
|
|
27
16
|
|
|
28
|
-
|
|
17
|
+
Free. Local-first. No account required.
|
|
29
18
|
|
|
30
19
|
---
|
|
31
20
|
|
|
32
|
-
##
|
|
33
|
-
|
|
34
|
-
### Capture happens automatically
|
|
21
|
+
## What aide-memory closes that rules files don't
|
|
35
22
|
|
|
36
|
-
|
|
23
|
+
Static rules files (CLAUDE.md, .cursorrules) and skills are useful for always-on guidance, but they have four real limits:
|
|
37
24
|
|
|
38
|
-
- **
|
|
39
|
-
- **
|
|
40
|
-
- **
|
|
41
|
-
- **
|
|
42
|
-
- **PostToolUse**: records what was recalled so re-reads don't re-prompt
|
|
43
|
-
- **PreCompact**: clears session tracking before context compaction so post-compact reads re-prompt cleanly. The rules file separately tells the agent to save active plans, decisions, and constraints before compaction summarizes the session.
|
|
25
|
+
- **No unified convention or structure.** A team-wide guideline, a personal style preference, an area-specific decision, and a stack fact all blur into one file. The whole file gets injected on every turn, even when most of it might not be relevant to the area the agent is working in.
|
|
26
|
+
- **Manual capture.** Corrections and area knowledge from conversations don't make it back into the file on their own.
|
|
27
|
+
- **Tool-specific by default.** What you teach your agent in Claude Code doesn't carry to Cursor unless you copy the file over manually.
|
|
28
|
+
- **Unscoped recall.** Even when context is captured, nothing prompts the agent to look up what's relevant when it opens a specific file. The whole file lands in context, or nothing does.
|
|
44
29
|
|
|
45
|
-
|
|
30
|
+
aide-memory adds the layer those gaps leave open: scoped, layered, auto-captured-and-recalled memory with git as the team-sync substrate. Coexists with rules files; doesn't replace them.
|
|
46
31
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
Four layers organize the knowledge:
|
|
50
|
-
|
|
51
|
-
| Layer | What it captures | Example |
|
|
52
|
-
|---|---|---|
|
|
53
|
-
| **preferences** | How a contributor likes to work | "Prefer modular component structure, separate concerns into smaller files" |
|
|
54
|
-
| **technical** | Facts not obvious from code | "Dashboard data fetching uses React Query with stale-while-revalidate" |
|
|
55
|
-
| **area_context** | Decisions tied to code areas | "Settings panel uses progressive disclosure; new sections follow the expand/collapse pattern" |
|
|
56
|
-
| **guidelines** | Team-wide principles | "Mock external calls at the network boundary in tests, not at the function boundary" |
|
|
57
|
-
|
|
58
|
-
Recall ranks `area_context` first (most specific), then `technical`, then `preferences`, then `guidelines`. Scoped memories rank above project-wide ones.
|
|
59
|
-
|
|
60
|
-
### Git-synced for teams
|
|
32
|
+
---
|
|
61
33
|
|
|
62
|
-
|
|
34
|
+
## What aide-memory uniquely combines
|
|
63
35
|
|
|
64
|
-
|
|
36
|
+
The differentiator is the combination, not any single piece:
|
|
65
37
|
|
|
66
|
-
|
|
38
|
+
- **Layered + path-scoped recall.** Glob scopes (`src/auth/**`, `packages/api/**`) AND four typed layers (preferences / technical / area_context / guidelines). The agent gets only what's relevant for the file it's touching, ranked by how specific the layer is.
|
|
39
|
+
- **Hook-driven auto-capture.** Six hooks fire across the session lifecycle (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact). Capture happens because the editor invokes them, not because anyone remembers to.
|
|
40
|
+
- **File-per-memory + git-synced.** One JSON file per memory under `.aide/memories/`. `git add`, `git push`, `git pull` is the team-sync path. Personal preferences stay gitignored; team-shared memories travel with the repo.
|
|
41
|
+
- **Cross-tool.** Claude Code and Cursor read the same store today. Deeper integration for other editors may come based on user feedback.
|
|
42
|
+
- **Local-first.** SQLite cache + JSON files on your disk. Memory content stays on your machine. Anonymized usage counts ship to PostHog by default; disable with `AIDE_TELEMETRY=off`.
|
|
43
|
+
- **Uses your existing agent.** No LLM calls of its own. The model in your editor does the reasoning.
|
|
67
44
|
|
|
68
45
|
---
|
|
69
46
|
|
|
70
|
-
## Quick
|
|
47
|
+
## Quick Start
|
|
71
48
|
|
|
72
49
|
```bash
|
|
73
|
-
# 1. Install
|
|
50
|
+
# 1. Install + initialize
|
|
74
51
|
npm install -g aide-memory
|
|
75
52
|
aide-memory init
|
|
76
53
|
|
|
77
54
|
# 2. Restart your editor so the MCP server registers
|
|
78
|
-
#
|
|
79
|
-
#
|
|
55
|
+
# Cursor: Cmd+Q to quit, then reopen, then enable in Settings → MCP
|
|
56
|
+
# Claude Code: start a fresh session in this project
|
|
80
57
|
|
|
81
|
-
# 3. Store a memory
|
|
82
|
-
aide-memory remember "
|
|
83
|
-
--layer area_context --scope "src/components/dashboard/**"
|
|
58
|
+
# 3. Store a memory (or just talk to your agent and let hooks capture it)
|
|
59
|
+
aide-memory remember "API responses must use camelCase keys" --layer guidelines
|
|
84
60
|
|
|
85
61
|
# 4. Recall context for a path
|
|
86
|
-
aide-memory recall src/
|
|
62
|
+
aide-memory recall src/auth/
|
|
87
63
|
|
|
88
|
-
# 5.
|
|
64
|
+
# 5. Search across memories
|
|
65
|
+
aide-memory search "authentication"
|
|
66
|
+
|
|
67
|
+
# 6. Share with your team
|
|
89
68
|
git add .aide/memories/
|
|
90
|
-
git commit -m "Capture
|
|
69
|
+
git commit -m "Capture team conventions"
|
|
91
70
|
git push
|
|
92
71
|
```
|
|
93
72
|
|
|
94
|
-
Full walkthrough: https://aide-memory.dev/docs/quick-start
|
|
73
|
+
Full walkthrough: https://aide-memory.dev/docs/quick-start.
|
|
95
74
|
|
|
96
75
|
---
|
|
97
76
|
|
|
98
77
|
## What's in the box
|
|
99
78
|
|
|
100
|
-
- **7 MCP tools
|
|
101
|
-
- **13 CLI commands
|
|
79
|
+
- **7 MCP tools** for the agent: `aide_recall`, `aide_remember`, `aide_update`, `aide_forget`, `aide_search`, `aide_memories`, `aide_import`
|
|
80
|
+
- **13 CLI commands** for you: `init`, `recall`, `remember`, `update`, `forget`, `search`, `list`, `stats`, `recall-log`, `config`, `sync`, `migrate`, `cleanup`
|
|
102
81
|
- **6 hooks** wired into the editor at `init` (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact)
|
|
103
82
|
- **4 typed memory layers** with personal/shared split for preferences
|
|
83
|
+
- **Local SQLite cache** rebuildable from JSON files at any time
|
|
104
84
|
- **FTS5 keyword search** plus optional semantic search via Transformers.js or Ollama
|
|
105
|
-
- **
|
|
85
|
+
- **Configurable**: hook modes, scope-depth dial, recall caps, injection budgets, Stop schedule
|
|
86
|
+
- **Version update notice**: when a newer version is on npm, the SessionStart hook surfaces an "update available" line in chat (Claude Code) and a matching note in the auto-regenerated Cursor rules file
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Storage shape
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
.aide/ # in your project (committed; personal prefs gitignored)
|
|
94
|
+
├── memories/
|
|
95
|
+
│ ├── preferences/
|
|
96
|
+
│ │ ├── personal/ # gitignored, your private prefs
|
|
97
|
+
│ │ └── shared/ # tracked, team-shared prefs
|
|
98
|
+
│ ├── technical/ # tracked, stack and integration facts
|
|
99
|
+
│ ├── area_context/ # tracked, decisions for specific code areas
|
|
100
|
+
│ └── guidelines/ # tracked, team and project principles
|
|
101
|
+
├── config.json # local configuration with every public knob
|
|
102
|
+
└── config-reference.md # auto-generated key/default/description listing
|
|
103
|
+
|
|
104
|
+
~/.aide/projects/<hash>/ # in your home dir (per-machine, never committed)
|
|
105
|
+
└── memory.db # SQLite cache (rebuildable from the JSON above)
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Each memory is a single JSON file:
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
|
|
113
|
+
"layer": "technical",
|
|
114
|
+
"what": "Apollo client uses persisted query hashes; raw queries 404 in prod",
|
|
115
|
+
"why": "Discovered when the staging-vs-prod query mismatch broke checkout",
|
|
116
|
+
"scope": "src/graphql/**",
|
|
117
|
+
"contributor": "ahmed",
|
|
118
|
+
"tags": ["api-contract", "graphql"],
|
|
119
|
+
"shared": true
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
JSON files are the source of truth. SQLite is a rebuildable cache; delete `~/.aide/projects/<hash>/memory.db` and it reconstructs from the JSON on the next run.
|
|
106
124
|
|
|
107
125
|
---
|
|
108
126
|
|
|
109
|
-
##
|
|
127
|
+
## How recall works
|
|
110
128
|
|
|
111
|
-
|
|
129
|
+
When the agent calls `aide_recall({paths: [...]})`, the engine:
|
|
112
130
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
-
|
|
117
|
-
- Which hooks are active (disable per-file blocking, turn off correction detection)
|
|
118
|
-
- Personal vs shared preferences (gitignored or committed, configurable per-project)
|
|
131
|
+
1. Loads memories whose scope matches at least one of the requested paths (with parent inheritance, so querying `src/` returns memories scoped under `src/`).
|
|
132
|
+
2. Sorts by **scope match first** (scoped beats project-wide), then **layer priority** (`area_context` > `technical` > `preferences` > `guidelines`), then **scope specificity** (deeper scopes rank higher) and keyword relevance.
|
|
133
|
+
3. Caps at `recall.limit` (default 20) before returning.
|
|
134
|
+
4. **Layer-diversity rebalance**: when the total result set is below `recall.layerDiversityMinLimit` (default 5), under-represented layers swap up so each enabled layer is at least represented.
|
|
119
135
|
|
|
120
|
-
|
|
136
|
+
For conceptual searches ("where do we handle auth tokens?"), prefer `aide_search` over `aide_recall` since keyword + semantic search surfaces memories that path-scoping alone would miss.
|
|
121
137
|
|
|
122
138
|
---
|
|
123
139
|
|
|
124
|
-
## Privacy
|
|
140
|
+
## Privacy and telemetry
|
|
141
|
+
|
|
142
|
+
**Code and memory content never leave your machine.** Memories are JSON files on your disk, the SQLite cache is local, and the MCP server runs over stdio.
|
|
125
143
|
|
|
126
|
-
|
|
144
|
+
Telemetry is on by default. Only event types and machine-anonymous counts are sent: event name, a SHA256-hashed `hostname:username` for deduplication, platform, arch, Node version. Memory content, file paths, query strings, the number of memories you have, and any other user-identifying data are never sent. The sender IP is not transmitted (`$ip: null`, `$geoip_disable: true`), so location is not derived from events. To turn it off:
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
# Option 1: env var (per-shell)
|
|
148
|
+
export AIDE_TELEMETRY=off
|
|
149
|
+
|
|
150
|
+
# Option 2: persistent config (per-project)
|
|
151
|
+
aide-memory config telemetry.enabled false
|
|
152
|
+
```
|
|
127
153
|
|
|
128
154
|
---
|
|
129
155
|
|
|
@@ -131,11 +157,56 @@ Memory content stays on your machine. Telemetry is on by default — only event
|
|
|
131
157
|
|
|
132
158
|
| Editor | Status |
|
|
133
159
|
|---|---|
|
|
134
|
-
| **Claude Code** | Reference adapter.
|
|
135
|
-
| **Cursor** | Full hook + MCP wiring. Cmd+Q and reopen after `init`, then toggle aide-memory ON in Settings
|
|
160
|
+
| **Claude Code** | Reference adapter. Restart your session after `init` so the MCP server registers. |
|
|
161
|
+
| **Cursor** | Full hook + MCP wiring. Cmd+Q the app and reopen after `init`, then toggle the aide-memory MCP server ON in Settings → MCP. |
|
|
162
|
+
| **Devin CLI** | Full hook + MCP wiring (0.6.0+); near-Claude-Code parity since Devin's hooks are Claude-Code-compatible. Teaching ships as a scoped `.devin/skills/aide-memory` skill. |
|
|
136
163
|
| **Windsurf, Codex, Copilot** | Rules template at launch. Deeper integration may come based on user feedback. |
|
|
137
164
|
|
|
138
|
-
Per-editor
|
|
165
|
+
Per-editor support: https://aide-memory.dev/docs/supported-editors.
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Configuration
|
|
170
|
+
|
|
171
|
+
`aide-memory init` seeds `.aide/config.json` with all public settings so you can see and edit them in one place.
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
aide-memory config <key> # read
|
|
175
|
+
aide-memory config <key> <value> # write
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Or hand-edit `.aide/config.json`; the JSON file is the source of truth. Hooks re-read it on every fire so changes propagate without restarting anything.
|
|
179
|
+
|
|
180
|
+
A few of the most-used keys:
|
|
181
|
+
|
|
182
|
+
| Key | Default | Description |
|
|
183
|
+
|---|---|---|
|
|
184
|
+
| `hooks.read.maxBlocks` | `1` | Max pre-read hard-blocks per file path per session. `0` disables the hook. |
|
|
185
|
+
| `hooks.edit.maxBlocks` | `1` | Same for the pre-edit hook. |
|
|
186
|
+
| `hooks.search.mode` | `"soft"` | Pre-search hook: `"soft"`, `"block"`, or `"off"`. |
|
|
187
|
+
| `hooks.correction.enabled` | `true` | Detect correction patterns in user messages. |
|
|
188
|
+
| `hooks.correction.escalate` | `"off"` | `"off"` — correction surfaces only as the in-turn soft hint. `"block"` — also write a flag so the next `Stop` fire reminds the agent if no memory was stored. |
|
|
189
|
+
| `hooks.stop.mode` | `"block"` | `"block"` — scheduled `Stop` fires `decision:"block"` with a softened reason + brand chrome. `"off"` — silence scheduled fires. |
|
|
190
|
+
| `hooks.visible` | `true` | Show user-facing `aide-memory · ...` lines in the terminal. |
|
|
191
|
+
| `recall.minScopeDepth` | `1` | How specific a scope must be to surface per-file. Bump to `2` to demote `src/**`-style broad scopes to SessionStart only. |
|
|
192
|
+
| `memories.softening.threshold` | `10` | Below this total-memory count, hard blocks downgrade to soft nudges. |
|
|
193
|
+
| `memories.defaultShared` | `true` | Default `shared` value for new `preferences` memories. Per-call always overrides. |
|
|
194
|
+
|
|
195
|
+
Full reference: https://aide-memory.dev/docs/configuration.
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Comparison with alternatives
|
|
200
|
+
|
|
201
|
+
aide-memory, [claude-mem](https://github.com/thedotmack/claude-mem), and [engram](https://github.com/ayvazyan10/engram) all attempt to give AI coding agents persistent memory, but they take meaningfully different shapes.
|
|
202
|
+
|
|
203
|
+
**aide-memory** is the new entrant. It combines layered + scoped recall, hook-driven auto-capture, file-per-memory storage with personal/shared split, a single shared store across Claude Code + Cursor, and git as the team-sync substrate. Uses your existing agent's inference budget; no LLM calls of its own.
|
|
204
|
+
|
|
205
|
+
**claude-mem** is the more established project in the space, with editor support across Claude Code, Cursor, Gemini CLI, OpenCode, and OpenClaw. Continuous capture via PostToolUse hook + session-summary at Stop; SessionStart injection of compressed recent-sessions context; 3-tool MCP search workflow for on-demand detail. Storage is SQLite (FTS5) primary with optional Chroma for semantic search; runtime uses a Bun-managed worker. Per-folder timelines via Folder Context Files are opt-in (`CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED`), default-off. License: AGPL-3.0.
|
|
206
|
+
|
|
207
|
+
**engram** is a cognitive-architecture-style memory system: three typed memory types (Episodic, Semantic, Procedural) on a knowledge graph, with graph-expansion at recall and contradiction detection. Storage is SQLite or Postgres + HNSW vector index; surface is MCP-first plus REST / CLI / webhooks / Ollama proxy. License: MIT.
|
|
208
|
+
|
|
209
|
+
Full comparison table: https://aide-memory.dev/docs/comparison.
|
|
139
210
|
|
|
140
211
|
---
|
|
141
212
|
|
|
@@ -143,6 +214,7 @@ Per-editor details: https://aide-memory.dev/docs/supported-editors
|
|
|
143
214
|
|
|
144
215
|
- **Node.js 18 or later**
|
|
145
216
|
- **npm** (global install recommended; `npx` works as a quick try but path resolution can break across Node version upgrades or npx cache cleans)
|
|
217
|
+
- **Claude Code or Cursor** (for hook + MCP integration)
|
|
146
218
|
|
|
147
219
|
No Docker. No external databases. No API keys. No cloud accounts.
|
|
148
220
|
|
|
@@ -150,19 +222,24 @@ No Docker. No external databases. No API keys. No cloud accounts.
|
|
|
150
222
|
|
|
151
223
|
## License
|
|
152
224
|
|
|
153
|
-
|
|
225
|
+
aide-memory is **proprietary freeware**: free to use today, source not public, not open source. See [LICENSE](LICENSE) for the exact terms. More features coming.
|
|
154
226
|
|
|
155
227
|
---
|
|
156
228
|
|
|
157
229
|
## Documentation
|
|
158
230
|
|
|
159
|
-
Full docs
|
|
231
|
+
Full docs at https://aide-memory.dev. Page directory:
|
|
160
232
|
|
|
161
233
|
- [Quick Start](https://aide-memory.dev/docs/quick-start)
|
|
162
|
-
- [Concepts](https://aide-memory.dev/docs/concepts)
|
|
163
|
-
- [
|
|
164
|
-
- [
|
|
165
|
-
- [
|
|
166
|
-
- [
|
|
167
|
-
- [
|
|
168
|
-
- [
|
|
234
|
+
- [Concepts](https://aide-memory.dev/docs/concepts), the editor-agnostic mental model
|
|
235
|
+
- [Features](https://aide-memory.dev/docs/features), what's in the box
|
|
236
|
+
- [Configuration](https://aide-memory.dev/docs/configuration), all config keys and what they do
|
|
237
|
+
- [Reference](https://aide-memory.dev/docs/reference), MCP tools + CLI commands side-by-side
|
|
238
|
+
- [Hooks](https://aide-memory.dev/docs/hooks), per-hook walkthrough
|
|
239
|
+
- [Architecture](https://aide-memory.dev/docs/architecture), how storage, hooks, and recall work
|
|
240
|
+
- [Supported Editors](https://aide-memory.dev/docs/supported-editors), per-editor table
|
|
241
|
+
- [Comparison](https://aide-memory.dev/docs/comparison), aide-memory vs claude-mem vs engram
|
|
242
|
+
- [FAQ](https://aide-memory.dev/docs/faq), common questions
|
|
243
|
+
- [Troubleshooting](https://aide-memory.dev/docs/troubleshooting), fix something broken
|
|
244
|
+
|
|
245
|
+
The repo's `docs/user/` tree carries short pointers to each canonical page on the website.
|