DocumentationOverview

aide-memory

Auto-captured, auto-recalled, path-scoped memory for AI coding agents and teams.

aide-memory captures decisions, preferences, and technical context as you work, recalls them when the agent is in the relevant area, and shares them with your teammates over git.

npm install -g aide-memory
aide-memory init

Free. Local-first. No account required.

The gap aide-memory closes

Rules files (CLAUDE.md, .cursorrules) and skills cover always-on guidance and procedures. They work well for that, but they leave gaps:

  • No area scoping. Everything blurs into one flat file. The whole file gets injected every turn, even when most of it isn’t relevant to what the agent is working on.
  • Manual updates. Rules files don’t stay current on their own. Area-specific context doesn’t fit cleanly in one document.
  • Cross-session gaps. The fix you taught your agent yesterday isn’t in today’s session by default.
  • Cross-teammate gaps. When a teammate opens the same area you’ve been working in, their agent starts fresh. Much of what you learned doesn’t carry over.
  • Tool-specific. What you teach Claude Code doesn’t travel to Cursor, or vice versa.
  • Unscoped recall. The whole file lands in context every turn. There’s no prompt for the agent to pull a relevant subset based on the file it just opened.

aide-memory fills these gaps alongside your rules files. They coexist.

How aide-memory closes them

1. Hooks prompt at the right moments

Six hooks fire across the session lifecycle:

HookWhenWhat aide-memory prompts
SessionStartSession begins or resumesInjects top preferences + guidelines + priority-always memories so the agent starts informed
PreToolUseBefore file read / edit / searchFirst read of a file with un-recalled scoped memories: prompts the agent to call aide_recall. Once recalled this session, subsequent reads are silent or soft-nudged if some scoped memories haven’t been recalled yet. Tunable.
PostToolUseAfter aide_recall / aide_remember / aide_searchRecords what was recalled so re-reads don’t re-prompt
UserPromptSubmitYou send a messageDetects correction patterns (“no, use X instead”) and prompts the agent to call aide_remember
StopAgent finishes a turnPeriodic reflection prompt (“anything worth remembering?”) on a tunable schedule (default ramps every 3 → every 5 → every 10 turns by session length)
PreCompactBefore context compactionClears session tracking so post-compact reads re-prompt cleanly

The rules file written at init also guides the agent to call aide_remember on corrections and decisions.

2. Memories are scoped to code paths and ordered by layer

Scopes are glob patterns relative to your project root (src/auth/**, packages/api/**). Glob inheritance: a memory scoped to src/** is available everywhere under src/, but a memory scoped to src/checkout/** only fires there.

Recall ordering: area_context ranks first (most specific to a code area), then technical, then preferences, then guidelines. Within a layer, scoped memories beat project-wide ones, deeper scopes beat shallower ones.

3. Four categorized layers

LayerWhat it capturesExample
preferencesAn individual contributor’s coding style or workflow”I write component files as Component/index.tsx + Component/Component.test.tsx, never co-located in the parent dir”
technicalFacts about the stack not obvious from code”Apollo client uses persisted query hashes; raw queries 404 in prod”
area_contextA decision or constraint specific to a code area”The billing module is event-sourced; new code appends events, never mutates balances directly”
guidelinesA team-wide or project-wide principle”Public API responses use {error: {code, message}} envelopes for any non-2xx status”

preferences further splits into personal/ (gitignored) and shared/ (committed). The other three layers are team-visible by default.

4. File-per-memory, git-synced

Each memory is one JSON file under .aide/memories/<layer>/. Commit, push, pull. A post-checkout git hook rebuilds the local cache after git pull so your teammates’ agents see the same context on their next file read.

# You captured a decision worth keeping
git add .aide/memories/area_context/
git commit -m "Capture event-sourced billing module convention"
git push
 
# Your teammate pulls
git pull
# Their agent's next read of src/billing/ surfaces:
# "1 memory exists for src/billing/. Call aide_recall."

No sync service, no auth, no daemons.

5. Project memory, not tool memory

Memories belong to your project, not to whichever tool you’re using. The same .aide/memories/ directory is read by Claude Code and Cursor today. Switch tools or hand off to a teammate and the memory store comes with the codebase.

6. Uses your existing agent

aide-memory does no LLM calls of its own. The model in your editor does the reasoning. The token cost is the tool descriptors (~2,900 tokens once per session) plus whatever the agent recalls.

What you get

  • 7 MCP tools: aide_recall, aide_remember, aide_update, aide_forget, aide_search, aide_memories, aide_import
  • 13 CLI commands: init, recall, remember, update, forget, search, list, stats, recall-log, config, sync, migrate, cleanup
  • 6 hooks wired into your editor’s lifecycle (Claude Code: full; Cursor: full hook + MCP wiring)
  • FTS5 keyword search plus optional semantic search via Transformers.js or Ollama
  • Local SQLite cache rebuildable from JSON files at any time
  • Tunable prompting cadence, recall scope dial, injection caps, Stop schedule, search mode, and more

Get started

Head to the Quick Start guide.

Or read more first:

HomeQuick Start