Pan your AI history for gold.

alluvia

Every conversation you've ever had with an AI tool is sediment. Most of it is sand — but scattered through it are the nuggets: ideas you never chased, solutions you solved once and forgot, threads you meant to finish. alluvia is the pan.

You think through problems in Claude Code. You debug in Cursor. You explore in ChatGPT. Each tool remembers nothing about the others, and neither do you. The idea you need today is sitting in a session from last spring, in a different app, under a title you'll never search for. alluvia finds it.

"I know I've already thought about this — resurface it inside the tool I'm using now, with citations, without giving another cloud service my raw history." That sentence is the product.

Local-first memory for AI-assisted work — across tools, with provenance and human judgment. Not another "AI memory": your raw sessions never leave the machine, every surfaced idea cites its source, and you rate what's gold.

alluvia ingests all of it into one local store, distills it into atomic ideas, clusters those into themes, and then does the part nothing else does: it finds the bridges — the places where your past self already met the problem your present self is holding.

A true story from alluvia's own validation gate: a security review in one tool flagged a server-side validation gap. alluvia connections linked it to debugging sessions in a different tool from 14 months earlier — same root cause, long forgotten. Then alluvia propose turned that bridge into a concrete fix plan, cited back to both sources. The human kept it. Every claim in this README traces to a logged validation gate — see docs/validation.

Sixty seconds

(full 60-second demo)

uv tool install alluvia    # or: pip install alluvia
alluvia demo               # see every lens in 30s — no API key, synthetic data
alluvia init               # then: detect your sources, set up your provider
alluvia refresh            # distill → embed → cluster → map (local embeddings)
alluvia recall "the thing I'm debugging"   # cited recall from your own history

One-shot trial without installing: uvx alluvia init.

The four lenses

$ alluvia themes            # D — your thinking, clustered
• Docker Issues  [84 sessions/2 sources]  (2025-03→2026-06)
• Refresh Token Storage  [9 sessions/2 sources]
    Insecure localStorage tokens vulnerable to XSS; approaches discussed...

$ alluvia connections       # A — bridges across tools and months
🔗 "no cross-check between ids enables forgery"   [tool-A · 2026-06]
   ↔ "service isn't storing the id on upload"      [tool-B · 2025-04]
   why: same missing validation, found twice, 14 months apart.

$ alluvia unfinished        # B — threads you keep circling, never closing
🧵 Test Infra Reorganization   open · 4 sessions over 388 days

$ alluvia propose           # C — new next-steps, grounded in YOUR notes
[prop:50bda956] Add server-side consistency check  (feasibility 4/5)
    ...cites: note:104966a3, note:93de85cc
$ alluvia rate prop:50bda956 --keep

Recall — the front door

$ alluvia recall "refresh token storage in the browser" --handoff

recall fuses your themes, bridges, and unfinished threads into a few cited hits — retrieval only, zero LLM spend — and --handoff prints a paste-ready block for whatever assistant you're in right now:

Relevant prior context from alluvia (query: "refresh token storage…"):

1. Auth token lifecycle [open] — refresh races and rotation.
   why: 2 of your prior notes match; thread status: open
   sources: claude-code · 2025-04-18; chatgpt-export · 2025-11-02

Treat this as prior context, not ground truth — verify against the current code.

Inside your assistant, the MCP tool recall_now does the same thing mid-conversation. And bare alluvia prints a now-view — open loops, fresh bridges, whether a refresh is due.

Plus a weekly digest (alluvia digest run --if-due) that brings ≤5 interrupt-worthy items to you — and stays silent when nothing clears the bar.

See it: the dashboard

alluvia serve --open        # http://localhost:8177

Five views over your map — corpus overview, theme bubbles by status, the cross-tool bridge graph, a weekly activity timeline with your longest-unfinished threads, and your full judgments history. One self-contained page, zero external requests, served only on 127.0.0.1.

Inside your assistant (MCP)

claude mcp add alluvia -- uv run --directory <repo> alluvia mcp

Eight tools let Claude Code / Cursor / any MCP client query your idea-map mid-conversation: "you circled this in April — here's where you landed."

Your machine, visible

alluvia status    # every path + size, store by data class, what's running
alluvia top       # live CPU/RAM/disk of alluvia processes + its LLM traffic
alluvia doctor    # diagnoses the install and repairs what's safe to repair

Concurrent sessions are safe by design (WAL store, single-writer refresh lock), and any alluvia process can be killed at any instant — everything done so far is saved and resumes on the next run.

What leaves your machine

Provider is your choice — Groq, OpenAI, or Anthropic. The whole product works end-to-end on Groq's free tier — no card, no cloud account, a real trial on your real history where nothing leaves your machine — with per-role model overrides (ALLUVIA_LLM_MODEL_PROPOSE=... for a stronger generator, cheap models for bulk extraction).

Rate limits are handled for you: every call runs behind a provider-agnostic governor with backoff, per-model circuit breakers, and automatic fallthrough across models (on Groq's free tier each model has its own daily budget — when one hits a wall, alluvia moves to the next and comes back later). If a stage still can't complete, alluvia refresh says so — per-stage counts plus the provider retry time — and finishes the rest of the map instead of failing. Pending labels and statuses retry automatically on the next refresh.

How it works

sources ─► ingest ─► RAW (never mutated) ─► distill ─► notes ─► embed
                                                                  │
              lenses ◄── themes/links/status ◄── cluster/link/track
                │
   CLI · MCP · weekly digest        ratings ─► the eval corpus (yours)

Three data classes with different guarantees: raw (source of truth, never touched), derived (rebuildable from raw — improve the pipeline, re-run, nothing lost), judgments (your ratings and digests — durable, never regenerated).

Bring your ChatGPT history

ChatGPT ingestion uses the official data export: ChatGPT → Settings → Data controls → Export data. When the ZIP arrives by email:

alluvia ingest --source chatgpt-export --path ~/Downloads/chatgpt-export.zip
alluvia refresh

Your ChatGPT threads join the same map as Claude Code and Cursor — that's where the cross-tool bridges come from.

Honest limits

• Windsurf/Antigravity transcripts live in schema-less protobuf stores; alluvia detects and skips them cleanly. ChatGPT ingestion uses the official data export (ZIP), not live capture.
• Generated proposals are guardrailed (must cite your notes, novelty-gated, feasibility-labeled) but they're LLM output — you rate, alluvia learns.
• All accepted trade-offs live in docs/DEBT.md, each with the condition that triggers fixing it.

Any source, one contract

Beyond the built-in adapters, anything that writes a simple normalized-session JSONL is a source:

alluvia ingest --source jsonl --path ./exports/

That's how multi-machine setups work with no cloud (aggregate your hosts' histories into one directory), and how tools we don't ship a parser for arrive already normalized. Community feeders welcome.

MIT · built local-first on purpose: the research this project started from found that for developers, trust in this category is owned data or nothing.