Lucid Memory

2.7ms retrieval. 743,000 memories/second. $0/query.

Memory for AI that works like yours—local, instant, persistent.

curl -fsSL https://lucidmemory.dev/install | bash

New in 0.6.0: Memory Consolidation — Lucid Memory is now self-maintaining. Background consolidation strengthens recent memories, decays stale ones, prunes weak associations, and manages visual memory lifecycle. New memories are checked against existing traces — similar content reinforces or updates rather than duplicating. 307 tests, 0 tsc errors.

New in 0.5.0: Episodic Memory — Claude remembers not just what happened, but how it unfolded — reconstructing the story of your debugging session, not just the fix. "What was I working on before the auth refactor?" now has an answer.

Why Lucid Memory?

We're not a vector database. We're the retrieval layer that makes vector databases obsolete for AI memory.

Pinecone stores vectors. We understand context.

_{Benchmarked on realistic developer workflows (50-200 memories). Full methodology: bun run bench:realistic && bun run bench:tokens}

vs Pinecone ($750M+ valuation)

Pinecone is a great vector database. But vector search isn't memory.

Lucid Memory retrieves 50% more relevant context (82.5% vs 55.3% recall), runs 10-20x faster (local vs cloud), costs nothing, and keeps your code private—all while understanding that what you accessed yesterday matters more than what you accessed last year.

The Numbers

5x more relevant context per token than claude-mem. 2x more than Pinecone. Same budget, 5x more useful memories.

82.5% recall vs 28.9% (claude-mem) and 55.3% (Pinecone) at equivalent token budgets. More of what you need surfaces.

100% on adversarial recency tests. Recent-but-irrelevant never beats old-but-relevant—unlike systems where recency overwhelms similarity.

Why?

1. Gist compression — Memories stored as ~37 tokens, not ~75. 5x more fit in context.
2. Cognitive ranking — MINERVA 2 cubing (sim³) suppresses weak matches before budgeting.
3. Multiplicative recency — Relevance × recency, not relevance + recency. Irrelevant stays irrelevant.
4. Spreading activation — Related memories activate each other. Co-edited files surface together.
5. No network — Everything local. 2.7ms, not 200ms.
6. Rust core — 743,000 memories/second throughput

Before & After

Without Lucid:

User: "Remember that bug we fixed in the auth module?"
Claude: "I don't have context from previous conversations..."

With Lucid:

User: "Remember that bug we fixed in the auth module?"
Claude: "Yes - the race condition in the session refresh. We fixed it
by adding a mutex around the token update. That was three weeks ago
when we were refactoring the middleware."

Install in 60 Seconds

macOS / Linux:

curl -fsSL https://lucidmemory.dev/install | bash

Windows (PowerShell as Administrator):

irm https://lucidmemory.dev/install.ps1 | iex

irm https://raw.githubusercontent.com/JasonDocton/lucid-memory/main/install.ps1 | iex

That's it. Your AI coding assistant now remembers across sessions.

lucid config show                         # View current configuration
lucid config set-mode per-client          # Switch to per-client databases
lucid config create-profile work          # Create a new profile
lucid config set-profile codex work       # Assign Codex to use the work profile
lucid config set-profile opencode work    # Assign OpenCode to use the work profile

How It Works

Most AI memory is just vector search—embed query, find similar docs, paste into context.

Lucid implements how humans actually remember:

Want the full picture? See How It Works for a deep dive into the cognitive architecture, retrieval algorithms, and neuroscience behind Lucid Memory.

Visual Memory

New in 0.3: Claude now sees and remembers images and videos you share.

When you share media in your conversation, Claude automatically processes and remembers it—not by storing the file, but by understanding and describing what it sees and hears. Later, when you mention something related, those visual memories surface naturally.

How it works:

• Images — Claude sees the image, describes it, and stores that understanding with semantic embeddings
• Videos — Rust parallel processing extracts frames and transcribes audio simultaneously; Claude synthesizes both into a holistic memory
• Retrieval — Visual memories are retrieved via the same cognitive model as text memories (ACT-R activation + semantic similarity)
• Automatic — No commands needed; share media, Claude remembers

Episodic Memory

New in 0.5.0: Claude remembers sequences, not just facts.

Most AI memory systems remember individual pieces of information in isolation. Episodic memory captures the temporal structure of your work sessions — the difference between knowing "we fixed an auth bug" and remembering the full story: investigation, root cause, fix, tests.

How it works:

• Automatic episode creation — Memories stored during a work session are grouped into episodes. New episodes start on time gaps (>5 min), project switches, or event count limits
• Temporal links — Events within an episode are linked with forward/backward associations. Forward links are stronger than backward (1.0 vs 0.7), matching how human memory works (Temporal Context Model)
• Temporal spreading — When you retrieve a memory, activation spreads to temporally linked memories, surfacing the surrounding context
• Narrative queries — Ask "what happened before X?" or "what came after Y?" to reconstruct work sequences

Memory Consolidation

New in 0.6.0: Memories aren't static — they evolve over time.

Before 0.6.0, every memory persisted forever with static encoding strength. Now, Lucid Memory runs background consolidation that mirrors how biological memory systems work during sleep.

How it works:

• Two-window consolidation — Micro-consolidation (every 5 min) strengthens recently accessed memories and decays stale ones. Full consolidation (every 1 hour) advances state transitions and prunes weak data.
• Reconsolidation — When you store something similar to an existing memory, the system routes it through prediction error zones: low PE reinforces the original, moderate PE updates it in place, high PE creates a new trace.
• Association lifecycle — Associations between co-retrieved memories are reinforced. Unused associations decay exponentially and get pruned below threshold.
• PRP encoding — High-importance memories activate a protein synthesis-dependent window that boosts encoding of subsequent stores for 90 minutes.

Procedural Memory

New in 0.4.0: Claude develops procedural memory—the "muscle memory" of coding.

After working in a project, Claude doesn't just remember files—it knows them. Like how you navigate your home without thinking, Claude builds instinctive knowledge of your codebase through repeated exposure.

How it works:

• Familiarity grows asymptotically — First access: ~9% familiar. 10th access: ~50%. 24th access: 70%+ ("well-known"). Diminishing returns, like real learning.
• Context is bound to location — Claude remembers what you were doing when you touched each file (debugging? refactoring? reading?)
• Session-aware associations — Files accessed together in the same session get 1.5x stronger links
• Workflow learning — Files worked on for the same task form associative networks (3x boost)
• Temporal retrieval — Recent memories get priority through 4-phase cognitive processing:
  1. Working Memory buffer (τ≈4s decay, 7±2 item capacity)
  2. Session decay modulation (recent = slower forgetting)
  3. Project context boost (in-project memories ranked higher)
  4. Session tracking (30-min activity windows)
• Graceful decay — Unused files fade, but well-known ones have "sticky floors"—procedural knowledge resists forgetting

The Science

Built on two foundational cognitive models:

ACT-R (Anderson, 1983) — Memories compete for retrieval based on activation:

• Base-level activation from recency and frequency
• Spreading activation through associations
• Retrieval probability from activation strength

MINERVA 2 (Hintzman, 1988) — Reconstructive retrieval:

• Probe-trace similarity with nonlinear activation (cubing)
• Strong matches dominate, weak matches contribute minimally
• Pattern completion from partial cues

B(m) = ln[Σ(t_k)^(-d)]

A(i) = S(i)³

A_j = Σ(W_i / n_i) × S_ij

For Developers

Want to embed the retrieval engine in your own project?

use lucid_core::{
    retrieval::{retrieve, RetrievalConfig, RetrievalInput},
    spreading::Association,
};

let input = RetrievalInput {
    probe_embedding: &probe,
    memory_embeddings: &memories,
    access_histories_ms: &histories,
    emotional_weights: &weights,
    decay_rates: &decays,
    associations: &[],
    current_time_ms: now,
};

let results = retrieve(&input, &RetrievalConfig::default());

use lucid_core::{
    retrieval::{retrieve, RetrievalConfig, RetrievalInput},
    spreading::Association,
};

// Your memory embeddings (from any embedding model)
let memories = vec![
    vec![1.0, 0.0, 0.0],  // Memory 0
    vec![0.5, 0.5, 0.0],  // Memory 1
    vec![0.0, 1.0, 0.0],  // Memory 2
];

// What you're looking for
let probe = vec![0.9, 0.1, 0.0];

let input = RetrievalInput {
    probe_embedding: &probe,
    memory_embeddings: &memories,
    access_histories_ms: &[vec![1000.0], vec![500.0], vec![100.0]],
    emotional_weights: &[0.5, 0.5, 0.5],
    decay_rates: &[0.5, 0.5, 0.5],
    associations: &[],
    current_time_ms: 2000.0,
};

let config = RetrievalConfig::default();
let results = retrieve(&input, &config);

for candidate in results {
    println!(
        "Memory {} - activation: {:.3}, probability: {:.3}",
        candidate.index,
        candidate.total_activation,
        candidate.probability
    );
}

let config = RetrievalConfig {
    decay_rate: 0.5,           // Base-level decay (0.5 = human-like)
    activation_threshold: 0.3,  // Retrieval threshold
    noise_parameter: 0.1,       // Randomness (higher = more random)
    spreading_depth: 3,         // Association traversal depth
    spreading_decay: 0.7,       // Decay per hop
    min_probability: 0.1,       // Filter threshold
    max_results: 10,            // Result limit
    bidirectional: true,        // Spread both directions
};

use lucid_core::spreading::Association;

let associations = vec![
    Association {
        source: 0,
        target: 1,
        forward_strength: 0.8,   // Source → Target
        backward_strength: 0.3,  // Target → Source
    },
];

References

Memory & Retrieval

• Anderson, J. R. (1983). The Architecture of Cognition
• Anderson, J. R., & Lebiere, C. (1998). The Atomic Components of Thought
• Hintzman, D. L. (1988). Judgments of frequency and recognition memory in a multiple-trace memory model. Psychological Review, 95(4), 528-551.
• Kahana, M. J. (2012). Foundations of Human Memory

Episodic Memory

• Tulving, E. (1972). Episodic and semantic memory. In E. Tulving & W. Donaldson (Eds.), Organization of Memory
• Howard, M. W., & Kahana, M. J. (2002). A distributed representation of temporal context. Journal of Mathematical Psychology, 46(3), 269-299.
• Eichenbaum, H. (2000). A cortical-hippocampal system for declarative memory. Nature Reviews Neuroscience, 1(1), 41-50.
• Zacks, J. M., Speer, N. K., Swallow, K. M., Braver, T. S., & Reynolds, J. R. (2007). Event perception: a mind-brain perspective. Psychological Bulletin, 133(2), 273.

Spatial Memory & Location Intuitions

• O'Keefe, J., & Nadel, L. (1978). The Hippocampus as a Cognitive Map
• Moser, E. I., Kropff, E., & Moser, M. B. (2008). Place cells, grid cells, and the brain's spatial representation system. Annual Review of Neuroscience, 31, 69-89.
• Squire, L. R. (1992). Memory and the hippocampus: A synthesis from findings with rats, monkeys, and humans. Psychological Review, 99(2), 195-231.
• Hebb, D. O. (1949). The Organization of Behavior

Memory Consolidation

• Stickgold, R., & Walker, M. P. (2013). Sleep-dependent memory triage. Nature Neuroscience, 16(2), 139-145.
• Nader, K., Schafe, G. E., & Le Doux, J. E. (2000). Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval. Nature, 406(6797), 722-726.
• Kandel, E. R. (2001). The molecular biology of memory storage: A dialogue between genes and synapses. Science, 294(5544), 1030-1038.
• Anderson, J. R., & Schooler, L. J. (1991). Reflections of the environment in memory. Psychological Science, 2(6), 396-408.

Visual Memory

• Paivio, A. (1986). Mental Representations: A Dual Coding Approach — Images and words are processed through separate but interconnected channels
• Standing, L. (1973). Learning 10,000 pictures. Quarterly Journal of Experimental Psychology, 25(2), 207-222. — Humans have remarkable capacity for visual memory
• Brady, T. F., Konkle, T., Alvarez, G. A., & Oliva, A. (2008). Visual long-term memory has a massive storage capacity for object details. PNAS, 105(38), 14325-14329.
• Tulving, E. (1972). Episodic and semantic memory. In E. Tulving & W. Donaldson (Eds.), Organization of Memory — Visual memories as episodic traces bound to context

Privacy & Data

Lucid Memory runs entirely on your machine. Your memories never leave your computer.

• Database location: ~/.lucid/memory.db (or memory-<client>.db / memory-<profile>.db if using isolation)
• What's stored: Text summaries of learnings, decisions, and context—not your source code
• Removing sensitive data: Use memory_forget tool to delete specific memories
• Auto-updates: Opt-in during installation; can be disabled in ~/.lucid/config.json
• Configuration: Client and database settings stored in ~/.lucid/config.json

The database contains project context that persists across sessions. Treat it like your shell history—useful for productivity, stored locally with standard file permissions.

License

GPL-3.0 — see LICENSE for details.

_{Built for AI systems that need memory with meaning, not just storage with retrieval.}