Concepts: the aide-memory mental model

aide-memory is a persistent memory layer for AI coding agents. It captures decisions, preferences, and technical context as you work, surfaces them when the agent is in the relevant area, and shares them with your teammates over git.

This page is the editor-agnostic mental model. For runtime UX inside a specific tool see Supported Editors; for config keys see Configuration; for the MCP tools and CLI commands see Reference.

Where aide-memory fits

Most coding agents already work with two kinds of context:

• Editor-level rules (CLAUDE.md, .cursorrules) carry always-on guidance, project conventions, and reference info that should be available on every turn. They’re a single flat document, no scoping, no categorization.
• Skills / sub-agents carry procedures the agent can invoke for specific tasks.

aide-memory adds a third surface: dynamic, scoped, categorized knowledge that grows with the code, captured automatically and recalled when the agent is in the relevant area. Rules cover always-on guidance; skills cover procedures; aide-memory covers what those don’t, the dynamic, area-specific decisions and preferences and team conventions that build up over time.

The three coexist. aide-memory doesn’t replace your CLAUDE.md or your skills. The mental model:

• Rules file = “things every agent in this project should always know” (style, project layout, common pitfalls)
• Skills = “procedures the agent can run for specific tasks”
• aide-memory = “the body of decisions, preferences, technical facts, and corrections that grows with your codebase, scoped to where each one applies”

1. Memories

A memory is a single JSON file under .aide/memories/<layer>/. It captures one unit of knowledge (a decision, a preference, a fact, a rule) with a scope (the code area it applies to) and a layer (what kind of knowledge it is). Memories are human-readable, diffable, and syncable via git.

2. The four layers

Layers separate how the knowledge is used. Recall and injection are prioritized by layer, so the agent gets the most context-relevant entries first.

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

3. Scopes

Every memory can carry a scope, a glob pattern describing which code area it applies to. Scopes are relative to your project root. Examples:

• src/auth/** matches the auth module across machines
• packages/api/server/** matches a monorepo subpackage
• (no scope) means project-wide; surfaces everywhere

Inheritance is the key property: a memory scoped to src/** surfaces for src/checkout/CartSummary.tsx. A memory scoped to src/checkout/** surfaces only inside checkout code. Scoping lets you attach context to specific areas without polluting recall in unrelated files.

How specific a scope must be to surface per-file vs SessionStart-only is tunable via recall.minScopeDepth (default 1, permissive). See Configuration for the visualization.

4. Hooks

Hooks are small scripts the editor runs at lifecycle points. aide-memory installs them at aide-memory init. They fire automatically so capture and recall happen without manual invocation.

Not every editor supports every channel. See Supported Editors for what each adapter ships today and Hooks for the script-by-script breakdown.

5. MCP tools

aide-memory ships a local MCP server with seven tools. The agent calls them during conversation; you can run the equivalent CLI commands. See Reference for full details.

6. Storage shape

.aide/
├── memories/
│   ├── preferences/
│   │   ├── personal/    # gitignored, private to you
│   │   └── shared/      # tracked, visible to team
│   ├── technical/
│   ├── area_context/
│   └── guidelines/
├── config.json          # local configuration with every public knob seeded
├── config-reference.md  # auto-generated key/default/description listing
└── cache/
    ├── memory.db        # SQLite cache (rebuildable, gitignored)
    └── recalled-paths-<sid>.txt  # session-scoped tracking

JSON files are the source of truth. SQLite is a rebuildable cache. Recall stats live only in the cache so per-machine usage data doesn’t end up in git.

7. Sync via git

Memories are files. Commit them, push them, pull them. A post-checkout git hook (installed at init) imports new or changed memory files into the local SQLite cache after git pull or branch switch. Conflicts resolve by updated_at timestamp; newer wins.

8. Recall strategy

When the agent calls aide_recall({paths: [...]}):

1. Path-matched memories: scoped globs that cover the requested paths (with parent inheritance: querying src/ returns memories scoped under src/).
2. Sort order: 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.
3. Cap: recall.limit (default 20) per call; remaining IDs come back as missingIds on the next pre-read fire so the agent can call aide_recall({ids: [...]}) for the next batch.
4. Layer-diversity rebalance: when results are below recall.layerDiversityMinLimit (default 5), under-represented layers swap up so each enabled layer is represented.

For conceptual searches (“where do we handle auth tokens?”), prefer aide_search over aide_recall since keyword (and optional semantic) search surfaces memories that path-scoping alone would miss.

9. What aide-memory does not do

• No LLM calls of its own. The model in your editor does the reasoning.
• No background distillation. Memories are what you (or the agent on your behalf) wrote. Call aide_update to change them.
• No remote storage. Memory content stays on your disk. Anonymized usage counts ship to PostHog by default; disable with AIDE_TELEMETRY=off.

Further reading

• Configuration, every config key, default, and which editors honor it
• Reference, MCP tools + CLI commands side-by-side
• Hooks, per-hook walkthrough
• Architecture, internals: storage, recall, sync
• Supported Editors, what each adapter ships today