Quick Start

Install in seconds. The next time the agent reads a file with a scoped memory, the hook prompts it to call aide_recall.

Prerequisites

Node.js 18 or later to run aide-memory.
Git is optional but recommended (for team sync, contributor detection, and the post-checkout cache rebuild). aide-memory works without it.

1. Install and initialize

From your project root:

npm install -g aide-memory
aide-memory init

Or try it without installing globally:

npx aide-memory init

The global install is recommended because aide-memory’s hooks and MCP server need to run on every session. npx works but the paths point to the npm cache, which can break if you switch Node versions or clean the cache.

Output (abridged):

Project initialized for aide-memory.
Created .aide/, six hooks, MCP config, rules files for Claude Code + Cursor.
.aide/config.json seeded with every public setting.

Total time: a few seconds.

This creates:

.aide/
  config.json                  # every public knob, ready to edit
  config-reference.md          # auto-generated key/default/description listing
  memories/
    preferences/
      personal/                # gitignored, your private prefs
      shared/                  # team-shared prefs
    technical/                 # facts about the stack
    area_context/              # decisions for code areas
    guidelines/                # team-wide principles
  cache/                       # SQLite cache (gitignored)

.claude/
  settings.json                # six-event hook registration
  rules/aide-memory.md         # Claude Code agent instructions

.cursor/
  hooks.json                   # six-event hook registration
  mcp.json                     # MCP server entry
  rules/aide-memory.mdc        # dynamically-regenerated Cursor rules

.mcp.json                      # MCP server entry for Claude Code

.git/hooks/post-checkout       # cache rebuild after git pull

Plus .gitignore entries for .aide/cache/ and .aide/memories/preferences/personal/.

2. Restart your editor

aide-memory’s MCP server only becomes available after the editor reads .mcp.json (Claude Code) or .cursor/mcp.json (Cursor) at session start. Both editors load these once at startup.

Claude Code: open a fresh session in this project (close + reopen the chat or run /clear and start a new session).
Cursor: Cmd+Q the app (don’t just close the window) and reopen. Then go to Settings → MCP, find aide-memory in the list, and toggle it ON.

You’ll know it worked when the agent can call aide_recall, aide_remember, etc. without errors. The hooks fire either way, but the hook messages tell the agent to call those tools, so they need to be available.

3. Store your first memory

aide remember "API responses must use camelCase keys" --layer guidelines

Output:

Stored memory (id: 1):
  Layer: guidelines
  What:  API responses must use camelCase keys

Add scope to target a specific code area:

aide remember "Dashboard uses skeleton loading, not spinners" \
  --layer area_context \
  --scope "src/components/dashboard/**"

Or just talk to your agent. When you correct it (“no, use composition here”), the UserPromptSubmit hook detects the correction and prompts the agent to call aide_remember for you.

4. Recall context

aide recall src/components/dashboard/

Output:

Recalled 2 memories for "src/components/dashboard/":

## Area Context
  [2] Dashboard uses skeleton loading, not spinners [src/components/dashboard/**]

## Guidelines
  [1] API responses must use camelCase keys

Memories are returned ranked by scope match → layer priority (area_context > technical > preferences > guidelines) → scope specificity.

5. What happens automatically

Once initialized, six hooks handle context capture without any manual effort:

SessionStart: at session begin or resume, injects top-N preferences + guidelines + priority-always memories into the agent’s starting context.
PreToolUse: before the agent reads / edits / greps a file (or calls an aide_* MCP tool), surfaces memory counts by layer. First read of a file with scoped memories is blocked until the agent calls aide_recall; later reads of the same file in the same session are silent or soft-nudged. Configurable.
PostToolUse: after the agent calls aide_recall / aide_remember / aide_search, records the recalled IDs so subsequent reads of the same path don’t re-prompt.
UserPromptSubmit: when you correct the agent (“no, use X instead”), detects the correction and prompts the agent to store it.
Stop: when the agent finishes a turn, periodic reflection nudge (“anything worth remembering?”) on a configurable schedule (default ramps every 3 / 5 / 10 turns).
PreCompact: before context compaction, clears session tracking so post-compact reads re-prompt cleanly.

Memories are JSON files under .aide/memories/. Commit them, push them, your teammates pull them.

git add .aide/memories/
git commit -m "Capture skeleton-loading decision for dashboard"
git push

The post-checkout hook on your teammate’s machine rebuilds their local SQLite cache after git pull so their agent sees the same context yours does, on the next file read in the relevant area.

Personal preferences (.aide/memories/preferences/personal/) are gitignored, so personal style stays personal. Shared preferences and the other three layers travel with the repo.

7. Common commands

# List memories
aide-memory list                                 # all
aide-memory list --layer preferences
aide-memory list --scope "src/components/**"
 
# Search
aide-memory search "composition pattern"
 
# Stats and recall log
aide-memory stats
aide-memory recall-log --limit 50
 
# Delete
aide-memory forget <memory-id>
 
# Reset everything (nuclear)
rm -rf .aide/ ~/.aide/projects/
aide-memory init

8. Configuration

Read or write any public setting:

aide-memory config <key>           # read
aide-memory config <key> <value>   # write

Common knobs:

embeddings.backend, "auto" (default), "transformers", "ollama", or "none"
hooks.visible, show / hide aide-memory · ... lines in your terminal (default true)
hooks.read.maxBlocks, max times per session pre-read can hard-block (0 disables, 1 default)
hooks.search.mode, "soft" (default), "block", or "off" for the Grep nudge
memories.softening.threshold, below this total-memory count, hard blocks become soft nudges (default 10)
memories.defaultShared, default shared value for new preferences memories (default true)

Or just edit .aide/config.json directly. The JSON file is the source of truth. See the Configuration page for the full schema and visualized walkthroughs.

9. Working across editors

aide-memory works with Claude Code and Cursor today. Install in any project:

aide-memory init

Both editors read the same .aide/memories/ directory. Memories captured in Claude Code are available in Cursor immediately, and vice versa.

Next steps

Concepts, the editor-agnostic mental model
Configuration, tune prompting, recall, injection, and more
Reference, the 7 MCP tools your agent calls plus all 13 CLI commands
Hooks, per-hook walkthrough
Supported Editors, per-editor table
Comparison, how aide-memory differs from claude-mem and engram
FAQ, common questions

Overview Concepts