Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Data Handling
This page is for reviewers who need one place to answer "what data does
ai-memory collect, where does it live, and what (if anything) leaves the
machine", usually for a security, legal, or data-protection review ahead of
internal approval. It restates facts from SECURITY.md, cited
by section below, alongside the operational docs it names; if the two ever
disagree, SECURITY.md is authoritative.
Default: local, no telemetry, one model download
ai-memory does not phone home. There is no analytics, crash reporting, or
usage telemetry built into the binary, and no background update check.
Everything it stores (wiki pages and the SQLite database) lives under a
single, operator-controlled data directory on the local filesystem
(SECURITY.md, "Local data confidentiality"). No stored data leaves the
host unless one of the opt-in paths below is explicitly enabled. The
embedding provider is the one most likely to matter to a reviewer,
since it decides whether stored content reaches a cloud API at all.
The out-of-the-box default is local embeddings: the config template leaves
embedding_provider unset, which selects in-process local embeddings
(all-MiniLM-L6-v2, 384-dim) with no API key and no cloud calls. That
default carries one network behavior: on the first start, when the model
files are not already present, the server downloads three files (~87 MB
total, sha256-pinned in source) from huggingface.co in the background,
and hybrid search enables on the next restart. Nothing stored is sent; the
transfer is a download, so your host's address and the timing of the
request are visible to Hugging Face and its CDN, and no content goes with
them. To avoid the download entirely, set embedding_provider = "none",
or pre-seed the files offline as
docs/airgapped-install.md and
docs/local-embeddings.md describe.
There is no encryption at rest in v1; ai-memory relies on OS filesystem
permissions (owner-only directories/files on Unix, ACLs on Windows;
SECURITY.md, same section).
The opt-in paths that send data externally
Each is off by default and requires a deliberate config change or command to turn on.
| path | what leaves the host |
|---|---|
embedding_provider = openai|voyage|google|openai-compat|copilot |
the text of every stored page |
llm_provider (and llm_fallbacks), off by default |
session observations and page text on consolidation, lint, bootstrap, dream, profile and auto-improve runs |
capture_assistant (double opt-in) |
the assistant's final-turn text |
AI_MEMORY_RERANKER=llm |
each live query + bounded page titles/snippets |
[[admission_webhooks]] |
every write's page path, frontmatter and body, POSTed to the URL you configured |
- Embedding provider. This is the broadest path by far, and the one
most relevant to a reviewer's usual question ("does our source
material reach a cloud provider?").
OpenAiEmbedder,VoyageEmbedder,GoogleEmbedder, andCopilotEmbeddereach call their provider's embedding endpoint for every page that needs a vector. This isn't limited to new writes: switching a running install fromlocalto a cloud provider triggers a backfill of the existing corpus (POST /admin/embed,ai-memory embed --force), so changing this setting later can retroactively send content that was previously local-only. Leaveembedding_provideronlocal(the default) to keep this off; seedocs/local-embeddings.md.openai-compatpoints at a self-hosted engine, so the destination is your own server. - LLM provider. Setting
llm_provider(orllm_fallbacks) turns on the model-assisted pipeline: consolidation, lint, bootstrap, dream, the cross-project profile digest, and the auto-improvement loop each send session observations and page text to the configured provider and receive generated pages and proposals back. Thecodex,copilot, andcursorprovider options spawn the vendor's own CLI, which talks to that vendor's cloud under your existing login. With no provider configured, every one of these features either runs rule-based locally or stays off; seedocs/ARCHITECTURE.md("Zero-LLM default path"). - Assistant/Stop capture (
SECURITY.md, "Assistant/Stop capture is opt-in and sanitized"). Persisting the coding assistant's final-turn text requires a double opt-in:capture_assistanton the server andinstall-hooks --capture-assistanton the client. Once enabled, captured text rides in the session's automatic handoff to the next session and flows into consolidation/reviewer prompts, so it reaches a cloud provider only through path 2. The flag is global to the install; there is no per-project exclusion once it's on. - LLM-based search reranking (
SECURITY.md, "Search reranking is an outbound-data opt-in"). SettingAI_MEMORY_RERANKER=llmsends each live query plus bounded page titles/snippets to the configured LLM provider. Leave this unset, or point it at a local provider, to keep queries and recalled snippets on-host. - Admission webhooks. Every wiki write (create, update, delete, and
the handoff lifecycle events) runs the configured webhook chain: each
[[admission_webhooks]]entry receives the page's path, frontmatter, and full body as a JSON POST, and may mutate or reject the write. The request carries only anX-Memory-Opheader naming the operation; no credentials are attached. Deletes send the path with no body. The URL is one you configured, so this sends content to infrastructure you chose, over whatever TLS it has (docs/admission-webhooks.md).
Paths 3 and 4 pass through a sanitizer that strips obvious credentials
before anything is transmitted. The sanitizer is documented as
best-effort, not a guarantee; see the "Stored-content prompt injection"
and reranking notes in SECURITY.md for the exact caveats. The embedding
path (1) sends full page text to the provider's embedding endpoint and is
not sanitized the same way, and neither are the LLM provider (2) and
admission webhook (5) payloads, so they are the paths to leave off when
stored content must not leave the server.
Two more network behaviors sit outside the table because they carry no stored content:
ai-memory upgrade, when you run it, queriesapi.github.comand downloads fromgithub.com. Nothing checks for updates in the background.auth login oidc-device(and theopenai-oauth,anthropic-oauth,copilotlogins) talks to the issuer or vendor token endpoints during login and token refresh. These calls carry credentials, never memory content.
Finally, a topology choice rather than a config key: with a remote
server_url, the lifecycle hooks and the external relay ship every
captured event to the host you point them at
(docs/external-lifecycle.md). The data handling is everything on this
page, but the host, and whoever administers it, are now outside your
machine.
Is this "personal data" under GDPR?
ai-memory stores developer-authored artifacts (wiki pages, session handoffs, entity extractions) derived from coding-agent sessions. It has no purpose-built handling for personal data (no user-profile fields, no consent-tracking, no data-subject-request tooling) because it isn't designed to process personal data as such. In practice this means:
- If your team's session content incidentally contains personal data (e.g. a commit message with a name, or free text a developer typed), that data is stored and retained exactly like any other memory content, under your own organization's control on infrastructure you run.
- ai-memory does not transmit that content anywhere on its own; the opt-in paths above are the only export mechanisms, and all are under your control.
- Treat this the same way you'd treat any local database your team operates: your organization is the data controller and decides retention, access, and disclosure. This document does not constitute legal advice; confirm classification with your own data-protection function.
Processor relationship
Self-hosted with no opt-in features enabled: there is no third party in the data path, so ai-memory does not create a data-processor relationship under GDPR Art. 28. If you configure a cloud LLM or embedding provider (for core functionality, capture, or reranking), that provider becomes your processor for the data you send it, under whatever agreement you have with them directly. ai-memory passes the data along and is not a party to that relationship.
Deletion / retention
Most data persists until removed, but two mechanisms expire some of it without operator action, both on by default:
- Decay eviction of cold episodic pages. The daily forget sweep
(
[maintenance] forget_sweep_interval_secs, default 86400) tombstones episodic pages whose relevance score falls below[decay] cold_threshold(default 0.20, with an ~80-day survival floor) and hard-deletes those tombstones after[decay] hard_delete_after_days(default 180). Semantic, procedural and pinned pages are exempt, and raw observations are kept (observation_retention_days = 0). - TTL pages. A page written with
expires_atis hidden after its expiry and hard-deleted by the next forget sweep; a TTL outrankspinned.
Everything else persists until removed. Deletion is filesystem-level: removing
the data directory removes everything in it. For scoped deletion, a per-project
purge operation exists and is isolation-safe: it cannot delete files or rows
belonging to a different (workspace_id, project_id) (SECURITY.md,
"Per-project isolation").
Network exposure (if you run the server non-loopback)
Binding the server beyond 127.0.0.1 is a separate, opt-in operational
choice unrelated to the data-export paths above. It controls who can reach
the API, not what ai-memory sends externally. See SECURITY.md's "Network
exposure when binding to non-loopback addresses" section and
docs/https-via-proxy.md before doing this.
Related documents
SECURITY.md: threat model, scope, vulnerability reporting.docs/sso.md: enterprise identity/SSO integration.docs/airgapped-install.md: offline/air-gapped installation.