Data directories
Every path Memtrace writes to — the graph in <cwd>/.memdb, job state in .memtrace, caches and credentials under the home directory — and what is safe to delete.
Overview#
Memtrace writes to three kinds of location: project-local directories next to the code you index, a per-user home directory for caches and credentials that are shared across every project, and — only if you opt in — files your team commits to the repo itself. Nothing is written outside these paths.
Inside your project#
| Path | What it holds | Survives |
|---|---|---|
<cwd>/.memdb | The knowledge graph: MemDB data directory — WAL, episodes, paged records, indexes, and manifest for every database it holds. This is the graph itself. | Deleted entirely by bare memtrace reset (or rm -rf .memdb/); a scoped memtrace reset <repoId> removes only that repo's records. |
.memtrace | Job-state directory: async indexing job records and similar transient runtime state for the current workspace. | Safe to delete between runs — it is rebuilt as jobs are created. |
.memtrace/embed.toml | Workspace-scoped embedder config, written by memtrace embed set --workspace. Requires a .memtrace-workspace marker claiming this directory. | Deleting it falls back to the home config file, then env vars, then the built-in default. |
.memtrace/team.toml | Committable, secretless config written by memtrace connect, pointing this workspace at a self-hosted team MemDB (endpoint, database, org — no token). | Removed by memtrace connect --disconnect; your license credentials are untouched. |
.memtrace-workspace | Zero-byte marker file. Its presence — and which repos it actually claims as members — is what lets a parent folder of sibling repos share one graph (a "Folder Group" workspace). | Removing it (or memtrace workspace unbless) never deletes index data; repos just resolve their own .memdb next run. |
The first time memtrace start runs inside a git repo, it offers to add .memdb to .gitignore for you. The graph is derived data — regenerable from your source — so it doesn't belong in version control.
Under your home directory#
These paths are shared across every project on the machine — caches, registries, and credentials that don't belong to any one repo.
~/.memtrace/
| Path | What it holds | Survives |
|---|---|---|
~/.memtrace/fastembed_cache/ | Downloaded ONNX embedding model files (the default jina-code model and any others you've used). Overridable via FASTEMBED_CACHE_DIR. | Safe to delete — the next embedding run re-downloads whatever model is active. |
~/.memtrace/embed-cache/ | The on-disk embedding cache, one redb file per repo (keyed by repo id) so wiping one repo's cache never touches another's. Capped by MEMTRACE_EMBED_CACHE_CAP_MB (default 2048 MB, 0 = disabled). | Safe to delete — embeddings are recomputed and re-cached on demand. Check size with memtrace embed cache-status. |
~/.memtrace/config.toml | Home-level embedder config written by memtrace embed set (without --workspace) — provider, model, dim, and remote settings. | Deleting it falls back to env vars, then the built-in default (local jina-code, 768d). |
~/.memtrace/last_health.json | Result of the most recent memtrace embed test — pass/fail, dim, latency — read back by memtrace embed status. | Safe to delete; status just reports "(never)" until the next test. |
~/.memtrace/watches.json | Persisted file-watcher registrations (origin manual or restored) so watched paths survive MCP disconnects and daemon restarts. | Safe to delete — watches are simply not restored on the next start. Restore-on-boot can be skipped with MEMTRACE_NO_WATCH_RESTORE=1. |
~/.memtrace/workspaces/ | The Named Workspace registry — repo membership for workspaces created with memtrace workspace create. | Deleting entries forgets that named workspace grouping; each repo's own .memdb is unaffected. |
~/.memtrace/telemetry/queue.jsonl | Locally queued, content-free telemetry events (usage, sanitized errors, crash breadcrumbs) awaiting the next flush. Written even with MEMTRACE_TELEMETRY=off, since the panic hook always leaves a local breadcrumb — it is simply never shipped when off. | Safe to delete — it is a send queue, not a record Memtrace reads back. |
~/.memtrace/uninstall.js | A copy of the uninstall script plus the backup manifest of every user-global config file the installer mutated (MCP registrations, skills, hooks). | Required for memtrace uninstall to restore pre-install bytes — don't delete it before uninstalling. |
~/.memtrace/session-ledger.jsonl | Session ledger backing session-review tooling. Overridable via MEMTRACE_SESSION_LEDGER. | Safe to delete — rebuilt from ongoing sessions. |
~/.memtrace/memtrace.pid | Daemon PID file, written when the daemon boots and deleted on clean shutdown. memtrace stop and memtrace reset read it first to signal the running daemon before falling back to other guards. | Safe to delete when no daemon is running — a stale PID just makes the next stop/reset fall back to their other kill paths. |
~/.memtrace/cortex.json | Local opt-out marker for Cortex decision memory. Overridable via MEMTRACE_CORTEX_CONFIG; MEMTRACE_CORTEX=off overrides both. | Safe to delete — removes the opt-out, so Cortex reverts to auto-on for entitled users. |
~/.config/memtrace/credentials.json
Your signed-in session: license key, session token and expiry, edition, and any MemDB connect tokens. Written by memtrace auth login and deleted by memtrace auth logout. This is the one credential file in the whole layout — everything else under ~/.memtrace/ is cache or state, never secrets.
What is safe to delete#
| Delete this… | …and this happens |
|---|---|
<cwd>/.memdb | The entire graph for this project is gone. Re-run memtrace start or memtrace index . to rebuild it from source — nothing is lost that isn't re-derivable from your code and git history. |
.memtrace (job state) | In-flight job bookkeeping is lost; harmless between runs. |
~/.memtrace/fastembed_cache, ~/.memtrace/embed-cache | Pure caches. The next run re-downloads the model and/or recomputes embeddings — slower once, then back to normal. |
~/.memtrace/watches.json, ~/.memtrace/last_health.json, ~/.memtrace/session-ledger.jsonl | State that gets rebuilt naturally as you keep using Memtrace — no action needed beyond re-arming a watch if you relied on auto-restore. |
~/.memtrace/memtrace.pid | Only matters while a daemon is running. If deleted while one is live, memtrace stop and memtrace reset simply fall back to their other kill paths instead of a direct PID signal. |
~/.config/memtrace/credentials.json | You are signed out. Next memtrace start (or an MCP client launching memtrace mcp) re-runs the device-flow sign-in. |
~/.memtrace/uninstall.js | You lose the ability to cleanly restore pre-install config bytes via memtrace uninstall — delete only after you've uninstalled, or don't plan to. |
memtrace reset and rm -rf .memdb/ are scoped to the graph directory — they never touch ~/.memtrace/ caches, your credentials, or a committed .memtrace/team.toml. The one exception is ~/.memtrace/memtrace.pid: memtrace reset reads it to stop the running daemon first, then deletes it, the same way memtrace stop does. To fully reset embedding config alongside the graph, pair a reset with memtrace embed set --yes-reset.
See also Embedding providers for the embed config precedence chain, memtrace reset, and Telemetry for what the queued telemetry file actually contains.