aide-memory 0.6.0 → 0.6.2

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 (2) hide show
  1. package/README.md +163 -86
  2. package/package.json +5 -3
package/README.md CHANGED
@@ -1,129 +1,155 @@
1
1
  # aide-memory
2
2
 
3
- **Auto-captured, auto-recalled, path-scoped memory for AI coding agents and teams.**
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
- **Website:** https://aide-memory.dev
7
+ ## TL;DR
6
8
 
7
- **Docs:** https://aide-memory.dev/docs
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
- **Install:** `npm install -g aide-memory && aide-memory init`
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
- ## The problem
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
- aide-memory fills these gaps. It sits alongside your rules files, not above or below. Rules files for static, always-on guidance. aide-memory for the dynamic, scoped knowledge that grows with the codebase.
17
+ Free. Local-first. No account required.
29
18
 
30
19
  ---
31
20
 
32
- ## How it works
33
-
34
- ### Capture happens automatically
21
+ ## What aide-memory closes that rules files don't
35
22
 
36
- Six hooks fire across the session lifecycle, installed by `aide-memory init`:
23
+ Static rules files (CLAUDE.md, .cursorrules) and skills are useful for always-on guidance, but they have four real limits:
37
24
 
38
- - **UserPromptSubmit**: detects corrections ("no, use X instead") and prompts the agent to store them scoped to the code area
39
- - **Stop**: periodic reflection ("anything worth remembering?") on a tunable schedule picks up decisions and findings
40
- - **SessionStart**: injects top preferences, guidelines, and priority-always memories so the agent starts with context
41
- - **PreToolUse**: before the agent reads or edits a file, checks if relevant memories exist for that path and prompts recall
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
- ### Recall is scoped
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
- Memories attach to code areas via glob scopes (`src/components/dashboard/**`, `packages/api/**`). When the agent opens a file, aide-memory matches the path against stored scopes and surfaces what's relevant to that area.
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
- Memories are JSON files under `.aide/memories/`. Commit, push, pull. A `post-checkout` git hook rebuilds the local cache after `git pull` so your teammate's agent picks up your context on their next file read. Personal preferences (`preferences/personal/`) are gitignored. Team conventions travel with the repo.
34
+ ## What aide-memory uniquely combines
63
35
 
64
- ### Cross-tool
36
+ The differentiator is the combination, not any single piece:
65
37
 
66
- Claude Code and Cursor read the same `.aide/memories/` directory. A memory captured in one tool is available in the other. Codex, Copilot, and Windsurf get a rules template at launch; deeper integration may come based on user feedback.
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 start
47
+ ## Quick Start
71
48
 
72
49
  ```bash
73
- # 1. Install and initialize
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
- # Claude Code: start a fresh session
79
- # Cursor: Cmd+Q, reopen, enable in Settings > MCP
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 "Dashboard uses skeleton loading, not spinners" \
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/components/dashboard/
62
+ aide-memory recall src/auth/
87
63
 
88
- # 5. Share with your team
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 dashboard conventions"
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**: `aide_recall`, `aide_remember`, `aide_update`, `aide_forget`, `aide_search`, `aide_memories`, `aide_import`
101
- - **13 CLI commands**: `init`, `recall`, `remember`, `update`, `forget`, `search`, `list`, `stats`, `recall-log`, `config`, `sync`, `migrate`, `cleanup`
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
- - **Version update notice** on SessionStart (Claude Code) + auto-regenerated Cursor rules file when a newer aide-memory is on npm
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
- ## Tunable
127
+ ## How recall works
110
128
 
111
- aide-memory ships with defaults you can adjust:
129
+ When the agent calls `aide_recall({paths: [...]})`, the engine:
112
130
 
113
- - How often the agent gets prompted to reflect and store context (`hooks.stop.schedule`; `hooks.stop.mode = "off"` silences scheduled prompts entirely)
114
- - Whether a detected correction escalates to a Stop reminder if the agent doesn't store it (`hooks.correction.escalate = "off"` default, or `"block"` for an explicit follow-up)
115
- - How specific a scope needs to be before a memory surfaces per-file vs session-start-only
116
- - How much context gets injected at session start
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
- `aide-memory init` seeds `.aide/config.json` with all public settings. Full reference: https://aide-memory.dev/docs/configuration
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
- Memory content stays on your machine. Telemetry is on by default — only event types and machine-anonymous counts (event name, hash of `hostname:username` for deduplication, platform, arch, Node version) are sent. The sender IP is not transmitted, so location is not derived from events. To turn it off: `AIDE_TELEMETRY=off` or `aide-memory config telemetry.enabled false`.
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. Start a fresh session after `init` so the MCP server registers. |
135
- | **Cursor** | Full hook + MCP wiring. Cmd+Q and reopen after `init`, then toggle aide-memory ON in Settings > MCP. |
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 details: https://aide-memory.dev/docs/supported-editors
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
- Free to use. See [LICENSE](LICENSE) for terms.
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: **https://aide-memory.dev**
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
- - [Configuration](https://aide-memory.dev/docs/configuration)
164
- - [Reference](https://aide-memory.dev/docs/reference)
165
- - [Hooks](https://aide-memory.dev/docs/hooks)
166
- - [Supported Editors](https://aide-memory.dev/docs/supported-editors)
167
- - [Comparison](https://aide-memory.dev/docs/comparison)
168
- - [FAQ](https://aide-memory.dev/docs/faq)
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.
package/package.json CHANGED
@@ -1,11 +1,13 @@
1
1
  {
2
2
  "name": "aide-memory",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
4
+ "mcpName": "io.github.aide-memory/aide-memory",
4
5
  "description": "Persistent memory layer for AI coding agents — your agent remembers what you taught it",
5
6
  "main": "dist/memory/index.js",
6
7
  "bin": {
7
8
  "aide": "dist/cli/aide-memory.js",
8
- "aide-memory": "dist/cli/aide-memory.js"
9
+ "aide-memory": "dist/cli/aide-memory.js",
10
+ "aide-memory-mcp": "dist/memory/cli.js"
9
11
  },
10
12
  "files": [
11
13
  "dist/cli/aide-memory.js",
@@ -50,5 +52,5 @@
50
52
  "type": "git",
51
53
  "url": "https://github.com/aide-memory/aide-memory"
52
54
  },
53
- "homepage": "https://aide-memory.dev"
55
+ "homepage": "https://aide-memory.com"
54
56
  }