Your Agent's Work Trace Is Episodic Memory. Store It Like Evidence.

Alluvia is a new MIT-licensed tool for searching AI-assisted work across Claude Code, Cursor, ChatGPT exports, and a normalized JSONL format. The project stores imported sessions in local SQLite, computes embeddings locally, and exposes cited recall through a CLI, dashboard, and MCP tools. Its Show HN post describes the idea in one line: mine your AI history locally.

That is useful. It also needs a sharper memory label than the usual “your chats become procedural memory.” They do not. A transcript is a record of an event. In memory terms, that makes it episodic.

Work traces are episodes, not procedures

An episodic memory says: on this date, in this tool, we tried two fixes, rejected one, and kept the other. It preserves sequence, context, and provenance. Alluvia is built around that material. It ingests sessions, derives notes, groups themes, finds connections, and points results back to their sources.

Procedural memory is different. It is the reusable method learned from one or more episodes: when two browser tabs race the same token refresh, serialize the refresh and test rotation under concurrency. A raw transcript may contain evidence for that procedure, but the procedure only becomes useful after extraction, validation, and revision. Otherwise an agent is replaying an old conversation as if it were a rule.

Reference memory is the third layer: source code, API contracts, architecture decisions, manuals, policies, and other material retrieved because it describes the system or the world. That is the familiar RAG layer. It answers “what is true in the current artifact?” Episodic memory answers “what happened?” Procedural memory answers “how should this kind of work be done?”

Collapsing all three into one vector index creates quiet failure modes. An old episode outranks a current specification. A discarded workaround returns as a recommended procedure. A procedure loses the evidence that justified it. Keep the classes separate, then connect them with citations.

Local-first does not mean private by default

Alluvia's documentation is specific about its data path. Raw conversations live in local SQLite and local embeddings stay on the machine. The dashboard binds to 127.0.0.1, and the project states that it has no telemetry. But distillation, labeling, and proposal generation can call a configured Groq, OpenAI, or Anthropic model after secret scrubbing. The raw store itself remains verbatim.

That distinction matters. “Local-first” describes architecture, not a complete privacy policy. Secret scrubbing before a provider call reduces risk; it does not prove that every personal detail, customer identifier, source fragment, or commercially sensitive fact has been removed. And a local database full of unredacted transcripts is still a sensitive database.

The project's source contract says raw imports are stored verbatim and never mutated. That is good for provenance. It also means retention cannot be an afterthought. Before importing history, decide which sources are allowed, which data classes may be stored, how deletion propagates into derived notes and backups, and whether remote model calls are permitted for that corpus.

Keep the evidence, not every byte forever

A safe memory system needs separate lifecycles. Raw episodes usually deserve the shortest retention because they contain the most context and the least filtering. Validated procedures can live longer, with an owner, a review date, and links back to the episodes that support them. Reference material should follow the lifecycle of its source system rather than a chat-history policy.

Derived data is not harmless. A theme label can reveal a confidential project. An embedding can preserve sensitive relationships even when the original prose is gone. A weekly digest can repeat personal data into a second store. Deletion has to cover the raw record, notes, embeddings, caches, exports, digests, and backups that can restore them.

Operational logs need an even tighter rule: never print full prompts, responses, environment values, or transcript bodies just because debugging is easier that way. Log record IDs, source type, timestamps, byte counts, model and policy version, redaction result, and failure category. Keep content access behind an explicit audited path. Encrypt the device and backups, restrict file permissions, and review any sync tool that can copy the database off the machine.

Alluvia's own security policy calls out session exfiltration, secret-scrubbing bypasses, dashboard exposure, and MCP writes or spend without machine-level opt-in. Those are the right boundaries to inspect. An MIT license and a local bind address are useful facts, not substitutes for a threat model.

The useful pattern is cited recall

The strongest part of Alluvia is not “agents remember everything.” It is narrower: resurface a small number of prior episodes, cite the source, and tell the next agent to verify them against the current code. The project's handoff example does exactly that.

That is the right default. Recall should produce evidence, not authority. A human or a controlled extraction step can promote a repeated lesson into procedural memory. Current documents remain the reference layer. Retention and access rules decide what is allowed to survive.

Work traces can make an agent less forgetful. Treat them carelessly and they also make a breach more complete. Both statements are true, and any serious memory design has to hold them at the same time.