AKM Storage Locations

This document is the authoritative reference for every location on disk where akm reads or writes persistent data: databases, event streams, config files, asset files, caches, locks, and OS-native task scheduler entries.

Path Variables

All paths below use these resolved base directories:

akm uses four XDG-compliant directories. Durable data (index.db, state.db, akm.lock) lives in $DATA; the event log is stored in the events table in state.db.

What May Live in $STASH/.akm

$STASH/.akm had no stated rule for what belongs there (itlackey/akm#889), and accumulated 165 MB / 1,523 files of it — 82% (135 MB) was the pre-0.9.0 .akm/proposals/ filesystem layout alone, superseded by the proposals table in state.db back in 0.9.0. Migrations moved the writers; nothing ever cleaned up the paths they left behind.

The rule: $STASH/.akm is for state that MUST travel with the content. Everything else belongs in $STATE, $CACHE, or $DATA.

"Must travel with the content" means: a fresh clone of the bundle on another machine, or a bundle synced via its own git remote, would lint or resolve differently without this file present. A cache, a log, or a queue that akm can rebuild or that only matters on the machine that wrote it does not qualify — even if akm happens to write it while operating on that bundle.

Confirmed exceptions (Tier 3 — correctly $STASH-local; do not move):

• $STASH/.akm/memory-cleanup/ (belief-transitions.jsonl + archive/) — the hard case. As of itlackey/akm#884, memory-cleanup/archive/ is a ref-resolution surface: when a contradictedBy edge points at a memory that was later pruned, resolution falls through to that memory's tombstone in memory-cleanup/archive/. If the archive is not present, that edge resolves differently (or not at all) — so the same bundle would lint differently depending on which machine ran the check. It must travel with the bundle content itself, not live in a per-machine $STATE/$CACHE dir. It is also directly recoverable user data (pruned memory bodies). This correctness reason was previously undocumented; it only became load-bearing with #884.
• <cwd>/.akm/config.json — project-scoped config overrides, walked up from cwd to the filesystem root and merged. Deliberately local to the project tree, the same idea as .editorconfig.
• $STASH/.akm/cache — used only when AKM_BUNDLE_DIR points at a transient path, as an isolation safety net (src/core/paths.ts) so a test harness pointed at a scratch bundle root cannot silently clobber the developer's real ~/.cache/akm. Not used in the normal (non-transient) case.

Known-dead residue (Tier 1 — cleaned up by #889): .akm/proposals/, .akm/runs.archived-<ts>/, .akm/archive/, .akm/graph.json, .akm/consolidate-journal.json, .akm/proposals.db, and .akm/mv-transactions/ are all superseded pre-0.9.0 layouts with no live reader or writer in src/. akm health reports any that still exist (with size) via the akm migrate status report; akm migrate apply deletes them on request. Nothing deletes this user data without that explicit opt-in.

Formerly-misplaced live writers (Tier 2 — relocated by itlackey/akm#890): distill-rejected/, eval-cases/, measurement/verdicts/, unresolved-sources/, and the improve-pipeline .lock files used to be written under $STASH/.akm but never met the "must travel with the content" rule above — none of them are read to resolve anything about the bundle content itself. Two of them now live under $STATE/$CACHE, namespaced per stash by getStashStateKey() (src/core/paths.ts) so two stashes on one machine never collide; the other three no longer exist:

akm migrate relocated pre-0.9.11 files still sitting at the old paths until 0.9.17-alpha.4 removed that step (scripts/akm-migrate/migrate/writer-relocation.ts). A file left at an old path is now inert: nothing reads it and nothing moves or deletes it, so remove it by hand if you want it gone. The pilot treatment file at $STASH/.akm/measurement/ (sibling to verdicts/) is manually-authored measurement input, not a writer output, and did not move.

SQLite Databases

Managed SQLite openers apply a busy_timeout of 30,000 ms. Journal mode is selected by AKM_SQLITE_JOURNAL_MODE (WAL, DELETE, or TRUNCATE) and defaults to WAL. When that default is used on a detected network filesystem, AKM falls back to DELETE; rollback-journal modes also set synchronous = FULL. Read-only existing-index handles apply the same busy timeout without mutating journal mode. Foreign-key policy is called out per database below.

$DATA/index.db — Main Search Index

Schema managed by ensureSchema() (src/storage/repositories/index-schema.ts). The current layout is 26 (index_meta.version, a layout marker, not a compatibility gate). It uses the shared opening pragma policy above with foreign keys ON. Vector search is an exact scan of the embeddings table.

Opened by:

• openIndexDatabase() — managed schema initialization, called by akm index and other index writers. Schema changes are applied in place: CREATE ... IF NOT EXISTS, ALTER TABLE ... ADD COLUMN / DROP COLUMN, drops of retired derived tables, and a one-time rebuild of the FTS table from entries when it still carries the layout-23 content copies. Crossing to layout 26 derives asset_links from the stored document_json. embeddings, utility_scores*, and llm_enrichment_cache are never dropped to cross a layout change. The one exception is the LLM entity graph (graph_meta, graph_files, graph_file_*), retired in 0.9.17-alpha.9: those tables are dropped unconditionally. A newer layout is refused, naming the upgrade.
• openExistingDatabase() / openReadonlyExistingDatabase() — no schema mutation; serve an older layout as-is (named once on stderr) and refuse a newer one (INDEX_SCHEMA_INCOMPATIBLE, "Upgrade akm to use this index.").

Retention: index.db is a regenerable derived cache. The one from-scratch rebuild is on-disk corruption (SQLITE_CORRUPT, #865): the file is deleted and rebuilt. An entries table older than layout 21 (no item_ref, or still the retired entry_key columns, as 0.9.1 wrote it) has its entries-keyed tables recreated; the LLM enrichment cache is kept. This path never modifies state.db. clearStaleCacheEntries() removes orphaned LLM cache rows. akm index VACUUMs the file at the end of a run after a layout migration (the writable opener sets index_meta.vacuumPending) and whenever more than half its pages are free, the threshold improve applies to state.db; each VACUUM appends an index_db_vacuumed event.

Table: index_meta

Known keys: version (layout marker), embeddingFingerprint (the embedding model the index currently serves), hasEmbeddings ("0" or "1"), vacuumPending ("1" after a layout migration, until akm index VACUUMs), ftsTotalsStale ("1" once a delete has taken a row out of entries_fts, until akm index rebuilds it).

Table: entries

Indexes: the UNIQUE item_ref constraint plus idx_entries_bundle on bundle_id, idx_entries_type on type, idx_entries_file_path on file_path, and idx_entries_derived_from on derived_from.

Virtual Table: entries_fts (FTS5)

BM25-weighted full-text search. Tokenizer: porter unicode61. Contentless (content='', contentless_delete=1): FTS5 stores only the inverted index, the text lives once in entries, and a row is addressed by its rowid. A SQLite older than 3.43 (no contentless_delete) gets the layout-23 content-bearing table instead; readers and writers handle both.

The canonical entry repository replaces this projection in the same SQLite transaction as its entries upsert. Deletes remove the FTS row before the parent entry. There is no caller-managed FTS dirty queue; a full FTS rebuild is reserved for explicit recovery of regenerable index state and for the totals below.

FTS5 cannot take a deleted row out of a contentless table's BM25 totals (its row count, and the token counts the average document length comes from), and has no command that recomputes them: delete and rebuild are refused on a contentless table. Every removal or replacement therefore leaves them one row too high, and an index that has been updated would score differently from a fresh one (#1048). A delete that removes a row stamps index_meta.ftsTotalsStale in its own transaction, whichever process made it, and the next akm index rebuilds the table from entries before it finishes (about a second at 25,000 entries; a run that removed or replaced nothing does not). The content-bearing table older SQLite gets subtracts a deleted row itself and is never rebuilt for this.

Rows carry rowid = entry_id, so a per-entry delete is a rowid lookup.

Table: entry_fragments

akm show <ref>#<fragment> splits this text at read time to resolve the selector (#937); nothing searches it. It is derived state and is replaced or removed in the same transaction as the parent's FTS row. Layout 24 and earlier also indexed each fragment in a second FTS5 table, entry_fragments_fts; the writable opener drops it.

Table: asset_links

Declared links (#935), layout 26. WITHOUT ROWID, keyed by (entry_id, ord).

Derived from the entry's document_json (src/indexer/links/declared-links.ts) and replaced in the same transaction as its entries upsert; deletes remove the rows before the parent. Whether a target exists is a join on entries.item_ref at read time; a memory target whose own entry is gone resolves to its .derived child. The graph_*-tabled LLM entity graph this superseded was retired in 0.9.17-alpha.9.

Table: embeddings

The embedding pass's cursor: an entry is (re-)embedded when it has no row for the configured model. upsertEntry deletes the row when an entry's embed_hash changes. Readers serve only rows of the current model: searchVec scores every one of them by cosine similarity in JavaScript (about 70 ms for 24k 1,024-dimension vectors).

Layout 24 and earlier also kept a sqlite-vec mirror of these rows, entries_vec. The writable opener drops it; dropping a vec0 table needs the extension, so an install without sqlite-vec leaves the unread table in place.

Workflow source indexing

Peer .md and .yml workflow sources compile directly to source IR version 1. The index stores the ordinary normalized entries row and metadata derived from that IR; there is no workflow-specific AST cache or parallel persisted source representation. Executable durable plans belong only to state.db.

Table: index_dir_state

Incremental indexing cache. Directory skipped if hash + mtime unchanged.

Table: llm_enrichment_cache

Primary key: (asset_ref, cache_variant).

Cache miss on body change or cache-variant change. Stale rows removed by clearStaleCacheEntries(). The cache can also be bypassed by internal forced re-enrichment callers.

What is cached: memory inference results.

Table: utility_scores

See Utility Score Pipeline below.

usage_events (search/show/feedback telemetry) is not an index.db table; it lives in state.db so deleting or rebuilding index.db cannot discard durable usage history. See the state.db section below.

Table: registry_index_cache

Registry index cache. TTL is enforced by getRegistryIndexCache().

Workflow Run State — tables in $DATA/state.db

workflow_runs, workflow_run_steps, workflow_run_units, and workflow_run_unit_attempts live in state.db. They use state.db's shared journal-mode/busy-timeout policy with foreign keys enabled. There is no separate workflow database or workflow-storage migration path. Runs persist until an explicit retention policy removes them.

Table: workflow_runs

New starts persist durable-v4-family plan irVersion: 5, the sole executable plan format. Pre-irVersion-5 stored plans are rejected rather than upgraded or replayed through another runtime.

Indexes: idx_workflow_runs_ref, idx_workflow_runs_status, idx_workflow_runs_scope_ref_status, idx_workflow_runs_agent_session.

Table: workflow_run_steps

Primary key: (run_id, step_id).

Table: workflow_run_units

The current status projection for execution units (one row per node in a run's execution graph), keyed (run_id, unit_id) with a FK to workflow_runs. The workflow_run_unit_attempts table is append-only; it receives every external reservation and terminal result, while this table remains the public status projection. Columns include node_id, parent_unit_id, phase, runner, model, status (pending/running/completed/failed/skipped), result_json, tokens, failure_reason, worktree_path, session_id, timing columns, and per-unit check-in/claim fields (last_checkin_at, attempts, claim_holder, claim_expires_at, engine). See docs/reference/workflows.md.

Table: workflow_run_unit_attempts

Append-only durable-v4 external-dispatch attempt ledger. Primary key: (run_id, unit_id, attempt). dispatch_id also has a unique index. A crash reclaim keeps the stable dispatch identity for the same attempt; an explicit retry appends a new numbered attempt instead of overwriting history.

$DATA/state.db — Migration-safe Durable State Database

Uses the shared journal-mode/busy-timeout policy with foreign keys ON. The immutable Flyway-pattern ledger has an explicit safety classification for every migration ID. Additive migrations and released migration 002's verified data-preserving task_history rebuild run automatically. Released migration 018's dead-lane table/column drops do not: an ordinary managed open stops at that boundary and directs the operator to akm upgrade or akm migrate apply. Before any install, those commands create a consistent sibling snapshot with VACUUM INTO, fsync it, require PRAGMA quick_check to report ok, and only then admits migration 018. The snapshot is named state.db.pre-018-drop-dead-lane-schema.<UTC-digits>.<UUID>.bak. Its randomized pathname is atomically reserved and held by descriptor; symlink, inode, and ownership replacement fail closed. It remains owner-only while SQLite writes and verifies it, then receives permissions no broader than state.db. One BEGIN IMMEDIATE window spans the locked ledger recheck, WAL-inclusive snapshot, migration 018 DDL, and ledger insert. Fresh-database privilege comes only from an atomically created file whose inode remains owned by that open; an existing or replaced path cannot inherit it. An existing file with no applied migration IDs—whether the ledger table is absent or empty—is rejected without writes by ordinary commands. Explicit upgrade binds the exact source inode, writes and verifies a state.db.pre-001-initial-schema.<UTC-digits>.<UUID>.bak copy before ledger creation or migration 001. One BEGIN IMMEDIATE transaction holds writer exclusion across that snapshot, ledger initialization, migration 001, and migration 002's table rebuild. The migration lock verifies that BEGIN actually opened a transaction before any body runs and that the transaction still exists before COMMIT. Snapshot source and target SQLite connections use descriptor-bound paths where the platform permits pathname replacement and fail closed if that binding is not available. Failed reserved backup paths are reported and retained, never removed by check-then-unlink cleanup. Unknown or divergent ledgers fail closed.

This is one narrow released-ledger gate, not a general database backup, restore, or cutover framework. Created on first durable state write.

Table: schema_migrations

Tracks applied migration IDs.

Table: events

Replaces events.jsonl. Indexed on event_type, ref, ts. Monotonic rowid replaces byte-offset cursor. Defined by migration 001-initial-schema in src/core/state/migrations.ts (CREATE TABLE IF NOT EXISTS events); no later migration alters it.

Indexes: idx_events_type on event_type, idx_events_ref on ref, idx_events_ts on ts.

Table: proposals

The proposal queue: pending proposals and the decided rows kept for the audit trail (archival is a status change, not a move). Replaces per-uuid JSON directories under $STASH/.akm/proposals/. Defined by migration 001-initial-schema; migration 006-proposals-pending-ref-source added the third index and 026-proposals-strip-legacy-fragment-refs stripped #fragment from stored refs. Row mapping and validation: src/storage/repositories/proposals-repository.ts (ProposalRow, proposalToRowValues, proposalRowToProposal).

Keys of metadata_json, each written only when the proposal has it:

Indexes: idx_proposals_stash_status on (stash_dir, status), idx_proposals_ref_status on (ref, status), idx_proposals_stash_status_ref_source on (stash_dir, status, ref, source).

Table: task_history

Replaces per-task JSONL files. Indexed on task_id, started_at.

Indexes: idx_task_history_task on task_id, idx_task_history_started on started_at.

Table: usage_events

Durable, non-regenerable telemetry lives in state.db, not the rebuildable derived index.

Indexes: idx_usage_events_entry, idx_usage_events_type, idx_usage_events_ref, idx_usage_events_source.

Preserved across index.db schema changes and full rebuilds. relinkUsageEvents() re-associates rows to new entry IDs via entry_ref after a full rebuild.

Table: legacy_state

Historical table installed by released state migration 020. The migration SQL and ledger id remain immutable for existing databases; current runtime code has no reader, writer, or cutover path for this table.

$DATA/logs.db — Task/Run Log Lines

Separate SQLite database from state.db (src/core/logs-db.ts, getLogsDbPath()). Uses the shared journal-mode/busy-timeout policy with foreign keys OFF. Structured replacement for grepping the per-run flat log files under $CACHE/tasks/logs/<task-id>/<ISO-ts>.log (that per-run text file is still written as a transitional human-readable tail). Can grow large in practice — live installs have been observed at roughly 1 GB — because every scheduled task run appends its stdout/stderr lines here with no default cap on total size (only an age-based purge, see below).

Table: task_logs

Indexes: idx_task_logs_ts on ts, idx_task_logs_task_id on task_id, idx_task_logs_run_id on run_id.

Retention: purgeOldTaskLogs() deletes rows older than 90 days by default; it runs as part of the improve maintenance stage (loop-stages.ts) alongside the state.db purges. Age-based only — there is no size cap, which is why the file can reach ~1 GB.

JSONL Event Streams

$CACHE/events.jsonl — Replaced by events table in $DATA/state.db

The JSONL file at $CACHE/events.jsonl is no longer read or written by akm.

Wire format (one object per line, historical reference):

{"schemaVersion":1,"ts":"2026-05-11T01:37:00.000Z","eventType":"<verb>","ref":"<type:name>","metadata":{}}

id was the byte offset of the line — assigned at read time via readEvents(), not stored on disk. In the new events table, the monotonic INTEGER PRIMARY KEY replaces the byte-offset cursor.

Event type catalog. EventType (src/core/events.ts) is an open string union, so this is the set of types the code writes at HEAD (every appendEvent/insertEventOnce call site, plus the retention pass's report(...) helper and the vacuum helper), not a closed list. Data & Telemetry groups the same set by area. A synthetic ref (for example proposals/_expiration) stands in for a stash-wide event.

Read API: readEvents(options) — filter by since, sinceOffset (row id cursor), type, ref, includeTags, excludeTags, runId (metadata.runId), and limit (the most recent N). Returns { events, nextOffset }. There is no polling loop (tailEvents was removed with akm log tail in 0.9.0); a consumer polls with sinceOffset.

Consumers and purpose:

$STASH/.akm/memory-cleanup/belief-transitions.jsonl — Belief State Log

One line per memory belief-state transition: { appliedAt, ref, parentRef, fromState, toState, reason, relatedRef? }. Observability only; no programmatic consumer reads this file.

JSON / Config Files

Markdown / Asset Files

Primary Bundle Content

All asset files live under $STASH/ in type-specific subdirectories defined by the PLACEMENT_SPECS map in src/core/asset/asset-placement.ts:

The workflows/ directory holds peer .md and .yml workflow sources. The tasks/ directory holds task source v4 .yml sources.

wikis/<name>/ is a separate convention: a bundle root recognized by the llm-wiki adapter, not a PLACEMENT_SPECS type directory. wiki is not an item type (see Classification).

Wiki File Structure

Each $STASH/wikis/<wikiName>/ (or any other bundle root the llm-wiki adapter recognizes — schema.md + pages/ is the probe) contains:

Improvement Pipeline Files

Lock / Sentinel Files

Cache Directories

Cache-backed bundles (git, website, npm) are materialised into $CACHE before indexing — each provider's sync() method (src/sources/providers/) is invoked through ensureSourceCaches(), and the materialised tree is then indexed like a local filesystem bundle.

OS-Native Task Scheduler Files

macOS (launchd)

Plist: ~/Library/LaunchAgents/com.akm.task.<id>.plist — XML plist. Contains label, ProgramArguments (akm task run <id> --bundle <bundle> --scheduled), StandardOutPath, StandardErrorPath, trigger (StartInterval or StartCalendarInterval), and EnvironmentVariables (PATH captured at install time, AKM_BUNDLE_DIR naming the syncing shell's working stash, and any other AKM_*_DIR that shell set explicitly).

Registered via launchctl bootstrap gui/<uid> <plist>.

Linux (cron)

No files written. User crontab edited in-place via crontab -l / crontab -. Each task is bracketed with sentinels, below one # akm:env block holding the PATH:

# akm:task <id> BEGIN
<cronexpr> AKM_BUNDLE_DIR=<working stash> /abs/akm task run <id> --bundle <bundle> --scheduled > ~/.cache/akm/tasks/logs/<id>.log 2>&1
# akm:task <id> END

(A command over 1,000 bytes runs sh <log dir>/.akm-cron-wrapper-<id>-<hash>.sh instead. Releases 0.9.0 – 0.9.17-alpha.6 wrote the same values into a $DATA/tasks/context/<sha256>.json descriptor per sync and named it in each row with --scheduler-context; nothing writes those files now.)

Disabled tasks get # akm:disabled prepended to the cron line.

Windows (Task Scheduler)

Task definition XML written to %TEMP%\akm-task-<id>-<ts>.xml, used to register via schtasks /Create, then deleted in the finally block. Persistent state is in the Windows Task Scheduler (OS-managed).

Companion Plugin State (Claude Code / OpenCode Harnesses)

These directories are written by the akm-plugins hook scripts (akm-plugins repo — the Claude Code and OpenCode integration layer that shells out to this akm CLI), not by the akm binary itself. They are part of the overall akm-ecosystem storage footprint and have been observed to grow large in practice (hundreds of MB) with no retention/prune policy in code today — no purge, TTL, or size cap was found in the hook sources.

$XDG_STATE_HOME/akm-claude/ (Linux/macOS default ~/.local/state/akm-claude/) — Claude Code Hook State

Path resolved by getHarnessStateDir("claude-code") / STATE_DIR in akm-plugins/claude/hooks/akm-hook.ts and akm-plugins/claude/shared/memory-events.ts.

$XDG_STATE_HOME/akm-opencode/ (Linux/macOS default ~/.local/state/akm-opencode/) — OpenCode Hook State

Same shared helpers as above with harness: "opencode" (getHarnessStateDir() / getCandidateLogPath() in akm-plugins/claude/shared/).

Note: the OpenCode plugin's curated-prompt files (CURATED_DIR in akm-plugins/opencode/index.ts) are written under the OS temp directory, not this state tier.

External / Read-Only Inputs

These paths are read by akm improve to scan for repeated failure patterns in agent session logs. akm never writes to them.

Utility Score Pipeline

How utility scores flow through the system:

akm search / akm show
  → insertUsageEvent()       → usage_events table (SQL aggregation)
  → bumpUtilityScoresBatch() → utility_scores (between-index EMA bump)
       formula: next = clamp(current + 0.1 × (1.0 − current), 0, 1)

akm feedback
  → insertUsageEvent()       → usage_events (signal column)
  → appendEvent()            → events table in state.db (for improve/distill/reflect pipeline)

akm index  (recomputeUtilityScores)
  → reads source='user' usage_events aggregates per entry
       selectRate   = min(1, show_count / search_count)
       feedbackRate = (positive_count − negative_count) / total_feedback
       effectiveRate = max(selectRate, feedbackRate)
       decay        = 0.7 ^ elapsedDays
       utility      = prevUtility × decay + effectiveRate × (1 − decay)
  → overwrites/decays the union of aggregated entries and existing utility rows

akm search  (ranking phase)
  → recencyFactor = exp(−daysSinceLastUse / 30)
  → score        *= min(1 + utility × recencyFactor × 0.5, 1.5)

usage_events and the general events log are both durable tables in $DATA/state.db. Utility recomputation reads usage telemetry there and joins entry ids against the regenerable index.db catalog in application code. Only source='user' contributes demand or utility. improve, task, audit, unknown, and unrecognized extension values remain inspectable telemetry but do not affect ranking, salience, real-query labels, or GRR.

Summary Index

Check src/core/paths.ts for the canonical path resolution functions (getCacheDir, getConfigDir, getDataDir, getDbPath, getStateDbPathInDataDir, getSemanticStatusPath, getStateDir, getStashStateKey, and the per-stash $STATE/$CACHE writer helpers getEvalCasesDir, getUnresolvedSourcesDir, getStashLocksDir).