FAQ

Is it free?

Yes. Free to use. More features coming. Source is not public; aide-memory is proprietary freeware, not open source.

Does it work with Cursor?

Yes. aide-memory ships with full hook + MCP wiring for both Claude Code and Cursor. The init command writes rules files for both editors and configures the MCP server. The same .aide/memories/ directory is read by both tools. Memories captured in Claude Code are available in Cursor immediately, and vice versa.

After init, start a fresh session in your editor (or restart it) so the MCP server registers. On Cursor, also enable the aide-memory MCP server in Settings → MCP.

Is it good for teams?

Yes, that’s a first-class story. Memories are JSON files under .aide/memories/. Commit them, push them, your teammates pull them. The post-checkout git hook on their 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 live under .aide/memories/preferences/personal/ and are gitignored, so personal style stays personal. The other three layers (technical, area_context, guidelines) and shared preferences travel with the repo.

Does it send data anywhere?

Only anonymized usage counts. Code and memory content never leave your machine. Memories are JSON files on your disk; SQLite is a local cache; the MCP server communicates over stdio, not HTTP.

The one network surface is anonymized PostHog telemetry, on by default. Each event is just a count (event type, a SHA256-hashed hostname:username for deduplication, platform, Node version) so we can see which features are used. Memory content, code, file paths, query strings, the number of memories you have, and any other user-identifying data are never sent. To disable telemetry entirely, set AIDE_TELEMETRY=off in your environment.

aide-memory stats (the local-only analytics dashboard) runs against a separate local-SQLite writer and is independent of the PostHog flag.

How does it compare to claude-mem?

claude-mem is the more established project in this space, with editor support across Claude Code, Cursor, Gemini CLI, OpenCode, and OpenClaw. Its capture is continuous: a PostToolUse hook records observations during the session, and a Stop hook compresses them into a session summary that gets injected at the start of the next session. On-demand drilling is via a 3-tool MCP search workflow.

aide-memory takes a different shape. Capture is event-typed (correction detection, periodic reflection, file-read prompt) rather than continuous; recall is per-file scoped (a small nudge when the agent reads a file with matching memories) rather than session-start broad-injection; storage is JSON files in your repo with git as the team-sync path rather than SQLite + optional Chroma.

The two tools optimize for different things. claude-mem leans toward broad context with searchable detail; aide-memory leans toward narrow, scoped recall and team handoff via git. See the Comparison page for the full table.

Can I use my own embedding model?

Yes. aide-memory supports configurable embedding backends. Use the bundled Transformers.js pipeline for zero-setup local embeddings, or connect Ollama for a model you’re already running.

aide-memory config embeddings.backend ollama
aide-memory config embeddings.model nomic-embed-text

@huggingface/transformers is in optionalDependencies; npm install -g aide-memory will attempt to install it (npm continues if it fails). Without either backend, aide-memory falls back to FTS5 keyword (BM25 ranking) with a LIKE fallback, which works well for most use cases.

What if I delete .aide/memories/?

The SQLite cache (memory.db) rebuilds from the JSON files automatically. The memories are recovered unless you also delete the .aide/ directory entirely.

If you delete the entire .aide/ directory, all memories are lost. Restore from git if you committed them.

How much disk space do memories use?

Memories are small: each is a single JSON file, typically 1-5 KB. Even with thousands of memories, the entire .aide/ directory is usually under 50 MB.

Can I share memories across projects?

Memories are scoped to a path within a project. To reuse a memory pattern in another project, copy the JSON file:

# From project A
cat .aide/memories/preferences/shared/<uuid>.json
 
# Copy to project B
cp .aide/memories/preferences/shared/<uuid>.json ../other-project/.aide/memories/preferences/shared/

Or commit to a shared git repo and pull in other projects.

What happens if two team members edit the same memory?

Each memory is its own JSON file, so two teammates adding new memories never collide; both files land cleanly via git. The only conflict path is when both teammates edit the same memory file, in which case git surfaces a normal text merge conflict that you resolve like any other:

git status
# Edit the conflicted .aide/memories/<layer>/<uuid>.json file
git add .
git commit -m "Resolve memory conflict"

aide-memory’s own sync logic (cache vs file disagreement) resolves by updated_at timestamp; git merges are yours.

Does aide-memory work offline?

Yes. Everything runs locally. No API calls, no cloud services, no authentication. Works offline from day one.

Can I migrate from claude-mem, engram, or my existing CLAUDE.md / .cursorrules?

For existing markdown rules files, aide_import can pull bullet lists or numbered items into a layer of your choice (the agent calls it; you pass the markdown content + target layer). It hasn’t been exercised end-to-end against every flavor of competitor export, so treat it as best-effort for now and open an issue if you hit something.

For claude-mem and engram, there’s no automated migration today; the storage formats differ enough (vector DB / typed stores vs JSON files) that a clean translation needs more work. Starting fresh with aide-memory and letting hooks capture as you go is the recommended path.

Does aide-memory replace CLAUDE.md / .cursorrules / skills?

No. aide-memory complements them. CLAUDE.md and .cursorrules cover static, always-relevant project guidance. Skills cover procedures. aide-memory adds dynamic, scalable, scoped, layered, auto-captured and auto-recalled memory on top. The three coexist; aide-memory doesn’t sit above or below the others.

The init command writes its own rules files (.claude/rules/aide-memory.md and .cursor/rules/aide-memory.mdc) that teach the agent when to call each MCP tool; your existing rules files keep doing their job alongside.

Does aide-memory cost extra inference money?

aide-memory itself does no LLM calls of its own; the model in your editor handles the reasoning. The cost surface is the tokens the agent spends on the seven MCP tool descriptors plus whatever it pulls back from aide_recall / aide_search. The descriptors are designed to be small, the recall payloads are scoped to the file the agent opened, and the SessionStart injection is capped by injection.maxChars (default 1200 chars). Net: aide-memory is built to cost less per turn than dumping a flat rules file every turn, but if you store thousands of broadly-scoped memories with narrow caps, your token usage will go up. Tune via injection.maxChars and recall.minScopeDepth if it matters.

How do I report a bug?

Open an issue on GitHub: https://github.com/aide-memory/aide-memory/issues

Include:

• Your Node version (node --version)
• aide-memory version (aide-memory --version)
• Steps to reproduce
• Error output

How do I request a feature?

Open a discussion on GitHub: https://github.com/aide-memory/aide-memory/discussions

Can I contribute?

aide-memory is proprietary freeware; the source is not public, so external pull requests aren’t accepted. Bug reports, feature requests, and feedback are very welcome on the issue tracker.

Are memory scopes absolute or relative paths?

Relative, by convention and design. A scope like src/auth/** is interpreted relative to your project root, so the same memory works on every machine that pulls it from git: your teammate’s ~/projects/myapp/src/auth/middleware.ts and your ~/work/myapp/src/auth/middleware.ts both match the same src/auth/** scope. If you accidentally pass an absolute path as a scope, it ships in the JSON as-is and won’t match across machines, so stick to project-relative globs.

Will aide-memory drift like a rules file does?

It’s a real risk that any memory layer faces. Today, the rules file written at init nudges the agent to call aide_remember (and aide_update when something has changed) at corrections and decisions, and the Stop hook periodically prompts a reflection. That keeps capture current as work happens. We’ll see how drift plays out at scale and consider richer drift-mitigation tooling if it shows up as a real problem in practice. If you hit a specific drift scenario, open an issue.

How does path scoping work exactly?

Path scoping uses glob patterns with parent inheritance. Scopes are relative to your project root:

• A memory for src/** applies everywhere under src/
• A memory for src/components/** applies only under src/components/
• More specific scopes rank higher when multiple memories match
• Querying src/ returns memories scoped under src/ (parent inheritance)

When the agent opens a file, aide-memory matches the file path against all stored scope globs and returns the matching memories ranked by scope match → layer priority (area_context > technical > preferences > guidelines) → scope specificity.

recall.minScopeDepth tunes how specific a scope must be to surface on per-file recall. Default 1 (permissive) lets every scoped memory surface per-file. Bump to 2 or 3 for stricter scoping when you have many broad scopes; broad scopes still surface at SessionStart, just not on every file read.

Can I use aide-memory in a monorepo?

Yes. Two patterns work:

Single root .aide/:

monorepo/
├── .aide/                       ← shared across all packages
└── packages/
    ├── frontend/
    └── backend/

Use scoped memories like packages/frontend/** and packages/backend/** to keep recall narrow.

Per-package .aide/:

monorepo/
└── packages/
    ├── frontend/
    │   └── .aide/
    └── backend/
        └── .aide/

Each package’s memories stay isolated. Run aide-memory init in each package directory.

The first pattern is recommended unless you genuinely want hard isolation between packages.

What if the agent doesn’t call aide_recall?

The agent gets a nudge in the system message but isn’t forced to call the tool. If the agent decides the memory isn’t relevant, it skips the recall.

This is intentional: nudges respect the agent’s judgment. If memories are being ignored, check:

1. Is the memory’s path scope correct?
2. Is the memory description clear?
3. Is the nudge actually showing up in the logs?

You can also flip pre-read mode to a stronger gate:

# Already the default for first read of each file:
aide-memory config hooks.read.maxBlocks 1
 
# Disable the read hook entirely (no block, no soft nudge):
aide-memory config hooks.read.maxBlocks 0

How do I see nudges in the logs?

aide-memory surfaces its own activity as inline aide-memory · ... lines in your terminal when a hook fires (soft recalls, correction detected, session-start memory injection, Stop checkpoints). Default on. To hide:

aide-memory config hooks.visible false

Hooks still function (context injection + enforcement unchanged); only the user-facing lines are suppressed.

For lower-level debug logs:

DEBUG=aide:* aide-memory list

Or check your editor’s Claude Code / Cursor extension logs.

Why do I sometimes see “PreToolUse:Read hook returned blocking error”?

That label is rendered by Claude Code for any intentional hook block; it’s not an aide-memory crash. When aide-memory detects scoped memories for a file you’re about to read, it asks your agent to call aide_recall first so the context is loaded before the read. Claude Code’s TUI renders this enforcement with a hardcoded “blocking error” label that hooks cannot customize.

The reason text beneath the label tells you what’s happening (e.g. 3 memories for src/foo.ts not yet recalled. Call aide_recall). aide-memory also surfaces an accompanying aide-memory · prompting aide_recall for scoped memories (expected flow) line to confirm this is expected behavior.

We’ve asked Anthropic to add a non-alarming label option for intentional blocks. In the meantime, you have several ways to tune the frequency or disable blocks entirely; see the next question.

How do I tune per-file recall noise / performance?

If aide-memory feels too chatty when you open files (especially in large projects with many broad-scoped memories), you have a few dials:

• recall.minScopeDepth (default 1): how specific a scope must be to surface per-file. Bump to 2 to exclude src/**-style broad scopes from per-file recall (they still surface at SessionStart). 3+ for strict narrow-scope-only.
• recall.limit (default 20): max memories per aide_recall call. If a file has more matching memories, the agent gets bounded pagination via follow-up aide_recall calls with the next batch of IDs. Bump if you consistently hit the cap.
• memories.softening.threshold (default 10): below this total-memory count, hard blocks become soft nudges. Helps small projects not feel hostile.
• Scope your memories precisely when storing them. Writing with scope src/api/routes/** is less noisy than src/**. Only use broad scopes for genuinely project-wide facts (and consider priority: "always" at SessionStart for those instead).

aide-memory config recall.minScopeDepth 2
aide-memory config recall.limit 30

How do I reduce or disable hook blocks?

Several config knobs let you shape the block behavior:

aide-memory config hooks.read.maxBlocks 0
aide-memory config hooks.visible false

Can I use aide-memory without git?

Yes. Memories are stored locally in .aide/ either way. Without git, you don’t get automatic team sync and the post-checkout rebuild hook isn’t installed; everything else (capture, recall, search, layers, scoping) works the same. If you hit something that doesn’t, open an issue.

What if MCP isn’t enabled yet but the agent wants to remember something?

When MCP isn’t available (e.g. you ran aide-memory init and haven’t restarted the editor yet), the agent can fall back to writing JSON lines to .aide/pending-memories.jsonl. On the next MCP server start, those entries get ingested into the proper store automatically. So a correction captured before MCP is wired doesn’t get lost; it just lands when the server first starts. If you notice memories not appearing after a restart, open an issue.

To sync manually between machines, copy the .aide/ directory.