Troubleshooting

Common issues and how to resolve them.

”No .aide/ directory found”

Symptom: A CLI command (other than init) fails with No .aide/ directory found. Run aide-memory init first.

Fix: Run aide-memory init once in the directory you want to scope as a project. That directory becomes the project root for aide-memory; all subsequent commands run from there or any subdirectory work against the same .aide/.

Hooks not firing

Symptom: The agent never calls aide_recall before reading files, or never reflects on task completion.

Possible causes:

Hooks disabled in config. Check:

aide-memory config hooks.read.maxBlocks    # should be 1
aide-memory config hooks.edit.maxBlocks    # should be 1
aide-memory config hooks.correction.enabled  # should be true

Value 0 / false means that hook is disabled.

MCP server not picked up by your editor. Start a fresh session (or restart the editor) so the new MCP config loads. For Claude Code, check .mcp.json exists. For Cursor, check .cursor/mcp.json exists, Cmd+Q the app and reopen, and toggle the aide-memory MCP server ON in Settings → MCP.
Rules file missing or outdated. Regenerate:
```
aide-memory init --update-rules
```

Search returns nothing

Symptom: aide-memory search "keyword" returns No memories found matching "keyword".

Possible causes:

No memories stored yet. Check aide-memory stats. If total is 0, store some memories first.
Keyword mismatch. Search checks what and why fields. Try broader terms or partial words.
FTS5 not available. Search falls back to LIKE matching when the SQLite extension is not available.
SQLite cache out of sync. Rebuild:
```
aide-memory sync import
```

Memories not persisting across sessions

Possible causes:

JSON files not being written. Check that .aide/memories/ contains JSON files: ls .aide/memories/technical/. Each memory should have a <uuid>.json file.
SQLite cache stale. Force a rebuild: aide-memory sync import.
Wrong project root. The store uses a hash of the project root path to locate the SQLite cache. If you open the project from different paths (e.g., symlinks), the cache may differ. Stick to one canonical path.
Personal preferences are gitignored. Memories in .aide/memories/preferences/personal/ are intentionally gitignored. They persist locally but are not shared via git.

Recall returns too many/too few results

How scope matching works:

scope: null or scope: "project" matches everything (project-wide)
scope: "src/auth/**" matches any path under src/auth/
Parent inheritance: querying src/ will also return memories scoped to src/auth/**
Default limit is 20 memories per recall

Fixes:

Use more specific paths: aide recall src/auth/middleware.ts instead of aide recall src/
Add --limit via MCP: aide_recall accepts a limit parameter
Ensure memories have appropriate scopes. Project-wide memories (no scope) always appear.

Sync conflicts

Symptom: aide-memory sync import reports conflicts:

Conflict: memory abc-123 has local edits newer than incoming file. Keeping newer version.

Resolution: Conflicts are resolved automatically; the newer version wins (based on updated_at timestamp). No data is lost. To force the JSON file version:

rm -rf ~/.aide/projects/*/memory.db
aide-memory sync import

Editor integration issues

Claude Code:

Restart your Claude Code session after aide-memory init. Claude Code reads .mcp.json once at session start; new MCP servers don’t appear in an in-flight session.
Check .claude/settings.json exists and lists aide-memory hooks for SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact. If missing or stale: aide-memory init --force to re-install.
Check .claude/rules/aide-memory.md exists with the agent instructions. If missing: aide-memory init --update-rules.

Cursor:

Cmd+Q the Cursor app (don’t just close the window) and reopen so it picks up the new MCP config.
Toggle the aide-memory MCP server ON in Cursor → Settings → MCP.
Check .cursor/rules/aide-memory.mdc exists with alwaysApply: true in the frontmatter. If missing or stale: aide-memory init --update-rules.

See the Cursor editor page for the full UX walkthrough and the Claude Code editor page for the reference setup.

Update check warnings

Symptom: After every command, you see an update notice.

Fix: Update to the latest version:

npm install -g aide-memory@latest

Or disable update checks:

aide-memory config updates.check false

Malformed config.json

Symptom: Commands behave unexpectedly, or you see:

[aide-config] Malformed JSON in .aide/config.json, using defaults

Fix:

rm .aide/config.json
aide-memory init

This creates a fresh config with defaults. Your memories are not affected.

How to reset everything

If you need a clean start:

# 1. Delete the .aide directory (removes all memories and config)
rm -rf .aide/
 
# 2. Delete the SQLite cache
rm -rf ~/.aide/projects/
 
# 3. Re-initialize
aide-memory init

This destroys all stored memories. Only do this if you want a complete fresh start.

To keep memories but reset only the cache:

rm -rf ~/.aide/projects/*/memory.db
aide-memory sync import

Architecture Comparison