Reference: MCP tools + CLI commands

aide-memory exposes the same memory operations through two surfaces:

• MCP tools that your AI coding agent (Claude Code, Cursor) calls during a conversation
• CLI commands that you can run yourself in the terminal (and the agent can shell out to via Bash, if your rules permit)

Both share the same store, so a memory stored via aide_remember is the same one returned by aide-memory list. Either surface works for any of the shared operations; the agent can call the MCP tool or shell out to the CLI based on what your rules direct it to do.

At a glance

CLI-only operations (no MCP equivalent today): init, stats, recall-log, config, sync, cleanup. See the CLI-only operations section.

MCP schema cost. The seven tools’ combined descriptors are around 2,900 tokens (aide_recall ~550, aide_remember ~860, aide_update ~430, aide_search ~380, aide_import ~310, aide_memories ~250, aide_forget ~120). For comparison, GitHub’s MCP server is ~54k tokens. The cost lands once per session in the agent’s tool list, regardless of how often you call the tools.

Recall

Retrieve context for an area of the codebase before planning or making changes. Recall is path-scoped, layered, scope-specificity-ranked, and layer-diversity-balanced:

• Path-scoped: returns memories whose scope glob matches at least one of the requested paths, with parent inheritance (querying src/ returns memories scoped under src/).
• Layered: results sort by area_context first, then technical, then preferences, then guidelines.
• Scope-specificity-ranked: within a layer, scoped memories beat project-wide ones; deeper scopes beat shallower ones.
• Layer-diversity-balanced: when total results are below recall.layerDiversityMinLimit (default 5), under-represented layers swap up so each enabled layer is represented.
• Bounded-paginated: capped at recall.limit (default 20). If a path has more matches, the remaining IDs come back as missingIds on the next pre-read fire so the agent can call aide_recall({ids: [...]}) for the next batch.

MCP form

{
  "tool": "aide_recall",
  "arguments": {
    "paths": ["src/components/billing/"],
    "query": "event-sourced state"
  }
}

Parameters:

CLI form

aide-memory recall src/components/billing/

Output:

Recalled 4 memories for "src/components/billing/":

## Area Context
  [12] Billing migrated to event-sourced state in Q1 [src/components/billing/**]

## Technical Context
  [5] Public endpoints rate-limited 60 req/min/IP at the edge

## Preferences
  [8] Prefer cursor-based pagination for unbounded queries (from ahmed)

## Guidelines
  [1] Public API errors must include a stable machine-readable code

When to use: before starting work in a code area, before proposing plans, after context compaction, or when the PreToolUse hook prompts that memories exist.

Remember

Store knowledge that should persist beyond this conversation.

MCP form

{
  "tool": "aide_remember",
  "arguments": {
    "what": "Billing migrated to event-sourced state in Q1; new code should append events, never mutate balances directly",
    "layer": "area_context",
    "scope": "src/components/billing/**",
    "why": "Decided in Q1 architecture review",
    "contributor": "ahmed"
  }
}

Parameters:

CLI form

# Project-wide guideline
aide-memory remember "Public API errors must include a stable machine-readable code, not just a message" --layer guidelines
 
# Scoped technical fact
aide-memory remember "Production rate limit on public endpoints is 60 req/min per IP, enforced at the edge" \
  --layer technical \
  --scope "src/api/**"
 
# Preference with explicit contributor
aide-memory remember "Prefer cursor-based pagination for unbounded queries" \
  --layer preferences \
  --contributor "ahmed"

Flags:

When to use: after corrections, decisions, non-obvious discoveries, or when the Stop / UserPromptSubmit hook prompts.

Update

Update an existing memory’s content, scope, or context.

MCP form

{
  "tool": "aide_update",
  "arguments": {
    "id": 12,
    "what": "Billing migrated to event-sourced state in Q1; new code appends events. Use BalanceProjector to compute current balances; never read balance fields directly.",
    "scope": "src/components/billing/**"
  }
}

CLI form

aide-memory update 12 \
  --what "Billing migrated to event-sourced state. Compute balances via BalanceProjector." \
  --scope "src/components/billing/**"

Errors: Memory 99 not found. / No changes specified. Use --what, --why, --scope, or --tags.

When to use: when a convention has evolved, code has moved (scope change), or context needs correction.

Forget

Permanently delete a memory. There is no archive mode; deletion is final.

MCP form

{ "tool": "aide_forget", "arguments": { "id": 12 } }

CLI form

aide-memory forget 12

Output:

Deleted memory 12: "Billing migrated to event-sourced state in Q1"

When to use: information is wrong, decision was reversed, or a duplicate exists.

Search

Search memories by keyword, semantic similarity, or both. The mode parameter controls the search backend:

• auto (default): keyword first, semantic fallback when fewer than 3 keyword hits
• keyword: FTS5 BM25 only (LIKE fallback if FTS5 is unavailable)
• semantic: embedding similarity only (requires Transformers.js or Ollama backend)

MCP form

{
  "tool": "aide_search",
  "arguments": { "keyword": "rate limit", "mode": "auto", "layer": "technical" }
}

CLI form

aide-memory search "rate limit"
aide-memory search "billing" --layer area_context --limit 10

When to use: concept-level lookups (“where do we handle auth tokens?”, “any memories about the payment flow?”). Often a better first stop than recall when you’re not pinning a specific path.

List

List stored memories for transparency and management.

MCP form

{ "tool": "aide_memories", "arguments": { "layer": "preferences", "contributor": "ahmed" } }

CLI form

aide-memory list
aide-memory list --layer preferences
aide-memory list --contributor ahmed
aide-memory list --layer area_context --scope "src/billing/**"

Import

Import guidelines or technical context from a markdown document. Each bullet point, numbered item, or paragraph (>20 chars) becomes a separate memory.

MCP form

{
  "tool": "aide_import",
  "arguments": {
    "content": "# Testing Guidelines\n- Mock external calls at the network boundary, not the function boundary\n- Integration tests live in __tests__/integration/\n- Test data uses factories, not raw object literals",
    "layer": "guidelines",
    "context_label": "testing guidelines"
  }
}

When to use: seed knowledge from existing docs (TESTING_GUIDELINES.md, ARCHITECTURE.md, CONTRIBUTING.md). Headings, code blocks, and table rows are skipped; only bullet points, numbered items, and paragraphs are imported.

CLI-only operations

These have no MCP equivalent today. The agent can still shell them out via Bash if your rules permit; they’re typed as CLI-only because there’s no agent-relevant scenario where calling them via MCP makes more sense than via the CLI.

aide-memory init

Initialize a new .aide/ project directory.

aide-memory init                # standard
aide-memory init --update-rules # refresh rules files only (safe to run repeatedly)
aide-memory init --force        # overwrite existing files

Creates .aide/, six hooks, MCP config, rules files for both editors, .aide/config.json seeded with every public setting, .aide/config-reference.md. Adds .gitignore entries for .aide/cache/ and .aide/memories/preferences/personal/. Both init and init --update-rules are safe to run repeatedly; the rules files get rewritten with the latest template content each time.

aide-memory stats

Show memory analytics summary.

aide-memory stats

Memory Statistics

  Total memories: 45

  By Layer:
    Preferences: 8
    Technical Context: 15
    Area Context: 18
    Guidelines: 4

  Most Recalled (this machine):
    [5] Production rate limit on public endpoints is 60 req/min/IP (12x)
    [1] Public API errors must include a stable code (8x)

  By Source:
    conversation: 20
    hook: 12
    agent_discovery: 8
    import: 5

Recall counts are per-machine: they count how often you’ve recalled each memory locally, not how often the team has across all clones.

aide-memory recall-log

Tail the recall-log to see recent recall events. Useful for debugging what the agent fetched and when.

aide-memory recall-log --limit 50
aide-memory recall-log --since 2026-04-28T00:00:00Z

aide-memory config <key> [value]

Read or write configuration. Per-project (<project>/.aide/config.json).

# Read
aide-memory config memories.defaultShared       # → true
aide-memory config recall.minScopeDepth         # → 1
aide-memory config tags.presets                 # → ["architecture",...]
 
# Write
aide-memory config memories.defaultShared false
aide-memory config hooks.read.maxBlocks 0
aide-memory config hooks.stop.schedule '[{"every":5}]'
aide-memory config contributor "TeamBot"

You can also edit .aide/config.json directly; the JSON file is the source of truth. Hooks re-read it on every fire so changes propagate without restarting anything.

For the full key reference and visualized walkthroughs, see Configuration.

aide-memory sync import / aide-memory sync export

Reconcile JSON files and the SQLite cache.

aide-memory sync import     # JSON → SQLite (rebuild cache)
aide-memory sync export     # SQLite → JSON (fill gaps)

Conflicts (local SQLite has newer data than the JSON file) resolve by updated_at timestamp; newer wins. The post-checkout git hook runs sync import automatically after git pull or branch switch.

aide-memory cleanup

Remove stale session tracking files from .aide/cache/. Each session creates small tracking files (recalled-paths-{session_id}.txt, searched-queries-*, correction-pending-*); these are normally cleared by PreCompact and SessionStart, but crashed sessions leave orphans.

aide-memory cleanup                      # >7 days old (default)
aide-memory cleanup --older-than 24h
aide-memory cleanup --dry-run
aide-memory cleanup --all                # all tracking files regardless of age

Removing an active session’s tracking file is not destructive; the session re-prompts on the next read and re-populates tracking via aide_recall. No memory data is lost.