Storage Layout

AIDE data is stored in .aide/ at the project root, with one exception: session anchor caches live outside the project ($XDG_RUNTIME_DIR/aide/anchors/ on Linux, ~/.aide/anchors/ elsewhere) so hooks and the statusline can resolve a session's root without walking. Entries are removed when the session ends; a TTL sweep cleans up after crashed sessions. A .aide/.gitignore is automatically created on first session to separate machine-local data from shareable content.

Directory Structure

.aide/
├── memory/
│   ├── memory.db              # Primary database (BBolt)
│   ├── search.bleve/          # Full-text search index
│   ├── code/
│   │   ├── index.db           # Code symbol database
│   │   └── search.bleve/      # Code symbol search index
│   ├── findings/
│   │   ├── findings.db        # Static analysis findings
│   │   └── search.bleve/      # Findings search index
│   └── survey/
│       ├── survey.db          # Codebase survey entries
│       └── search.bleve/      # Survey search index
├── state/                     # Runtime state (HUD, session info, anchor.json, worktrees)
├── bin/                       # Downloaded aide binary
├── worktrees/                 # Git worktree directories (swarm mode)
├── _logs/                     # Debug logs (when AIDE_DEBUG=1)
├── config/
│   ├── aide.json              # Project-level configuration
│   ├── mcp.json               # Canonical MCP server config
│   └── mcp-sync.journal.json  # MCP sync deletion journal
├── blueprints/                # Local blueprint overrides (JSON)
├── cache/
│   └── remotes/<name>/        # Subscription checkouts (git clones of peer context repos; machine-local, rebuilt by sync)
├── shared/                    # Exported decisions and memories
│   ├── decisions/             # One markdown file per topic
│   └── memories/              # One markdown file per category
├── skills/                    # Project-specific custom skills
└── .gitignore                 # Auto-generated

Git Tracking Rules

Gitignored (machine-local runtime data)

These are binary databases, runtime state, and machine-specific files that shouldn't be committed:

Path	Purpose
memory/	BBolt database + Bleve search index (binary, non-mergeable)
state/	Runtime state (HUD output, session info, worktree tracking)
bin/	Downloaded aide binary
worktrees/	Git worktree directories for swarm mode
cache/	Subscription checkouts — git clones of peer context repos
_logs/	Debug logs (when AIDE_DEBUG=1)
config/mcp.json	Canonical MCP server config (machine-specific sync state)
config/mcp-sync.journal.json	Tracks intentional MCP server removals

Shared via git

The shared/ directory is explicitly un-ignored (!shared/ in .gitignore):

Path	Purpose
shared/decisions/	Exported decisions as markdown (one file per topic)
shared/memories/	Exported memories as markdown (one file per category)

Files use YAML frontmatter + markdown body, making them useful as LLM context even without AIDE installed.

Tracked by default (committing optional)

Path	Purpose
config/aide.json	Project-level AIDE configuration
blueprints/	Local blueprint overrides (override or extend shipped)
skills/	Project-specific custom skills

Sharing Knowledge via Git

The share commands let you export and import AIDE knowledge through version control:

aide share export                    # Export decisions + memories to .aide/shared/
aide share export --decisions        # Decisions only
aide share import                    # Import from .aide/shared/
aide share import --dry-run          # Preview what would be imported

Automatic Import

Set AIDE_SHARE_AUTO_IMPORT=1 to automatically import from .aide/shared/ at session start. This means:

1. Team member A makes a decision and exports it
2. They commit .aide/shared/decisions/auth-strategy.md
3. Team member B pulls and starts a session
4. The decision is automatically imported into their local database

Import Conflict Resolution

When an imported entry relates to an entity already in the local database, AIDE applies a per-type rule:

Type	Key	Conflict rule	Net effect
Decisions	Topic + timestamp	Identical text to the current latest is skipped; otherwise the incoming decision is appended to the topic thread.	Append-only thread per topic
Memories	ULID	Same ULID + newer UpdatedAt → in-place update (ULID and CreatedAt preserved); otherwise skip. New ULID → appended.	Additive + edits

Design rationale. Decisions are a thread, not a single value: each SetDecision adds a new record keyed by topic:timestamp, and aide decision get <topic> returns the latest entry while aide decision history <topic> returns the full thread. So when a teammate commits a different decision for the same topic, the incoming entry becomes the new latest — the old one is still visible in history. This matches how ADRs work in most teams: superseded, not overwritten. Memories are accretive by ULID: every teammate's new learnings accumulate; in-place updates to an existing ULID only land when the incoming UpdatedAt is newer, so a teammate's refined content propagates without silently clobbering someone else's edit.

Practical notes:

• Memories keep their original ULID and CreatedAt on import. The same memory on every teammate's clone shares the same ID, so later edits land as in-place updates instead of creating duplicates.
• The updated=<timestamp> token inside a memory's <!-- aide:... --> comment is written only when the memory has been edited after creation. Legacy files without this token fall through to the additive path — existing IDs skip, new IDs are appended.
• The date= token is written in RFC 3339 format for full-precision round-trip; files from older aide versions using YYYY-MM-DD still parse.
• The PR merging the shared export is the review gate; there is no separate review-on-import step.
• Use aide share import --dry-run to preview what would change before a real import.

Export Format

Exported files are plain markdown with YAML frontmatter:

---
topic: auth-strategy
decision: JWT with refresh tokens
rationale: Stateless, mobile-friendly
timestamp: 2025-01-15T10:30:00Z
---

## Details

Using JWT tokens with refresh token rotation.
Access tokens expire after 15 minutes.

This format works as context for any LLM, even without AIDE installed.

Database Details

BBolt (memory.db)

AIDE uses BBolt — an embedded key-value store. A single memory.db file holds:

• Memories (with categories and tags)
• Decisions (append-only per topic)
• State (global and per-agent)
• Tasks (for swarm coordination)
• Messages (inter-agent communication)

Bleve (search.bleve/)

Bleve provides full-text search with:

• Standard word matching
• Fuzzy matching (Levenshtein distance 1)
• Edge n-grams for prefix matching
• N-grams for substring matching

Separate Bleve indexes exist for memories, code symbols, and findings.

Rebuilding Indexes

If search results seem stale:

aide memory reindex     # Rebuild memory search index
aide code clear         # Clear and rebuild code index
aide findings clear     # Clear and re-run findings

Compaction

BBolt never returns freed pages to the operating system. When records are deleted or rewritten (observe events ageing out, findings re-scanned, the code index rebuilt), the freed pages are reused for future writes but the .db file itself does not shrink — so a busy store's file can grow several times larger than the data it holds.

Compaction rewrites a store into a fresh, defragmented file and atomically swaps it in, returning the slack to the OS. It runs automatically when a long-lived store owner shuts down cleanly — the MCP server (the process the editor integration runs) or the aide daemon. A store is only rewritten when its free space is worth reclaiming (at least 1 MiB and 20% of the file), so tight files are left untouched.

Disable the automatic pass with maintenance.compact_on_exit=false in .aide/config/aide.json, or AIDE_MAINTENANCE_COMPACT_ON_EXIT=0.

To compact on demand:

aide maintenance compact

This reports per-store results. A store currently held open by a running aide process (daemon or MCP server) cannot be compacted while locked — stop that process first, or rely on the automatic on-exit pass.