widemem.ai

        .__    .___                                        .__
__  _  _|__| __| _/____   _____   ____   _____      _____  |__|
\ \/ \/ /  |/ __ |/ __ \ /     \_/ __ \ /     \     \__  \ |  |
 \     /|  / /_/ \  ___/|  Y Y  \  ___/|  Y Y  \     / __ \|  |
  \/\_/ |__\____ |\___  >__|_|  /\___  >__|_|  / /\ (____  /__|
                \/    \/      \/     \/      \/  \/      \/

<img src="docs/widemem-fish.png" width="48" align="middle" alt="widemem fish" />   Goldfish memory? ¬_¬ Fixed.

Background reading:

• Whitepaper: How LLMs Handle Memory. Technical paper on memory architectures, security risks, and in-weights personalisation.
• Why Context Windows Aren't Memory. The problem widemem solves.
• Your AI Memory Can't Tell a River Bank from a Savings Account. How YMYL classification actually works.
• Your AI Should Know When It Doesn't Know. Uncertainty-aware retrieval.
• Corrections log. Published claims that turned out wrong, and their fixes.

Because your AI deserves better than amnesia. ¬_¬

An open-source AI memory layer that actually remembers what matters. Local-first, batteries-included, and opinionated about not forgetting your user's blood type.

Look, AI memory has come a long way. Context windows are bigger, RAG pipelines are everywhere, and most frameworks have some form of "remember this for later." It's not terrible anymore. But it's not great either. Most memory systems treat every fact the same: your user's blood type sits next to what they had for lunch, decaying at the same rate, with the same priority. Contradictions pile up silently. There's no sense of "this matters more than that." And when you need to remember something from three months ago that actually matters? Good luck.

widemem is for when "good enough" isn't good enough.

widemem gives your AI a real memory: one that scores what matters, forgets what doesn't, and absolutely refuses to lose track of someone's prescription medication just because 72 hours passed and the decay function got bored. Think of it as long-term memory for LLMs, except it actually works and doesn't require a PhD to set up.

• Memories that know their place. Importance scoring (1-10) plus time decay means "has a peanut allergy" always outranks "had pizza on Tuesday". As it should. Not all memories are created equal, and your retrieval system should know the difference between a life-threatening allergy and a lunch preference.
• One brain, three layers. Facts roll up into summaries, summaries into themes. Ask "where does Alice live" and get the fact. Ask "tell me about Alice" and get the big picture. Your AI can zoom in and zoom out without breaking a sweat or making a second API call.
• YMYL or GTFO. Health, legal, and financial facts get VIP treatment: higher importance floors, immunity from decay, and forced contradiction detection. Two-stage classification (regex for obvious matches, LLM for implied content) catches "my chest hurts" as health while ignoring "the bank of the river." Read more ↗
• Conflict resolution that isn't stupid. Add "I live in Boston" after "I live in San Francisco" and the system doesn't just blindly append both. It detects the contradiction, resolves it in a single LLM call, and updates the memory. Like a reasonable adult would.
• Graceful memory-miss handling. Every retrieval returns a confidence level (HIGH / MODERATE / LOW / NONE) so your agent knows when memory has nothing relevant and can abstain instead of guessing. Three modes: strict (refuse on low confidence), helpful (hedge with related context), creative (offer to guess, with a warning). For high-stakes contexts where a wrong answer is worse than no answer.
• Local by default, cloud if you want. SQLite plus FAISS out of the box. No accounts, no API keys for storage, no "please sign up for our enterprise plan to store more than 100 memories". Plug in Qdrant or any cloud provider when you're ready. Or don't. We won't guilt-trip you.

---

Architecture

<p align="center"> <img src="docs/architecture.png" alt="widemem architecture diagram" width="100%"> </p>

---

TL;DR

Seven features, one library. Here's what widemem does that most memory systems don't:

| # | Feature | What it does | Why it matters | |---|---|---|---| | 1 | Batch conflict resolution | Single LLM call for all facts vs. existing memories | N facts equals 1 API call, not N. Your wallet will thank you. | | 2 | Importance + decay | Facts rated 1-10, with exponential/linear/step decay | Old trivia fades. Critical facts don't. | | 3 | Hierarchical memory | Facts to summaries to themes, auto-routed | Broad questions get themes, specific ones get facts. | | 4 | Active retrieval | Contradiction detection plus clarifying questions | "Wait, you said you live in San Francisco AND Boston?" | | 5 | YMYL prioritization | Health/legal/financial facts are untouchable | Some things you just don't forget. | | 6 | Confidence & abstention | Returns confidence level for every retrieval; abstains on memory miss | Lets the agent fall back to "I don't have that" instead of guessing | | 7 | Retrieval modes | fast / balanced / deep, pick your accuracy-cost tradeoff | Same system, three price points. You pick. |

600+ tests. Zero external services required. SQLite plus FAISS by default. Plug in OpenAI, Anthropic, Ollama, Qdrant, or sentence-transformers as needed.

---

Table of Contents

• Install
• Quick Start
• Configuration
• Scoring & Decay
• Providers
• YMYL (Your Money or Your Life)
• Hierarchical Memory
• Active Retrieval
• Temporal Search
• Uncertainty & Confidence
• Retrieval Modes
• History & Audit Trail
• Batch Conflict Resolution
• Prompt-Injection Sanitizer
• API Reference
• Claude Code Skill
• MCP Server
• Development
• Benchmarks
• Disclaimer & intended use
• Contact
• License

---

Install

pip install widemem-ai[faiss]

The [faiss] extra installs the default local vector store. Plain pip install widemem-ai installs the core only; you'll need at least one vector backend ([faiss] or [qdrant]) before WideMemory() will work. Python 3.10+ required.

Optional providers

pip install widemem-ai[anthropic]             # Claude LLM provider
pip install widemem-ai[ollama]                # Local LLM via Ollama
pip install widemem-ai[sentence-transformers] # Local embeddings (no API key needed)
pip install widemem-ai[qdrant]                # Qdrant vector store
pip install widemem-ai[mcp]                   # Model Context Protocol server
pip install widemem-ai[all]                   # Everything. You want it all? You got it.

---

Quick Start

Five lines to a working memory system. Six if you count the import.

from widemem import WideMemory, MemoryConfig

memory = WideMemory()

# Add memories
result = memory.add("I live in San Francisco and work as a software engineer", user_id="alice")

# Search
results = memory.search("where does alice live", user_id="alice")
for r in results:
    print(f"{r.memory.content} (score: {r.final_score:.2f})")

# Update happens automatically. Add contradicting info and the resolver handles it.
memory.add("I just moved to Boston", user_id="alice")

# Delete
memory.delete(results[0].memory.id)

# History audit trail
history = memory.get_history(results[0].memory.id)

That's it. No 47-step setup guide. No YAML files. No existential dread. Your AI just went from goldfish to elephant in six lines.

WideMemory also works as a context manager if you're the responsible type:

with WideMemory() as memory:
    memory.add("I live in San Francisco", user_id="alice")
    results = memory.search("where does alice live", user_id="alice")
# Connection closed automatically. You're welcome.

---

Configuration

Most defaults are sane, so a minimal config is usually enough:

from widemem import WideMemory, MemoryConfig
from widemem.core.types import LLMConfig, ScoringConfig, YMYLConfig

config = MemoryConfig(
    llm=LLMConfig(provider="openai", model="gpt-4o-mini"),
    scoring=ScoringConfig(decay_rate=0.01),
    ymyl=YMYLConfig(enabled=True),
    history_db_path="~/.widemem/history.db",
)
memory = WideMemory(config)

Full reference for every field, default, and tradeoff: docs/configuration.md.

---

Scoring & Decay

The Formula

Every search result gets a combined score. It's not rocket science, but it's close enough:

final_score = (similarity_weight * similarity) + (importance_weight * importance) + (recency_weight * recency)
final_score *= topic_boost   # if topic weights are set

• similarity: cosine similarity from vector search (0-1)
• importance: normalized from the 1-10 rating assigned at extraction (0-1)
• recency: time decay score (0-1), computed by the decay function
• topic_boost: multiplier from topic weights (default 1.0)

Decay Functions

Control how memories fade over time. Like real memories, but configurable. Unlike a goldfish, you can turn decay off entirely.

| Function | Formula | Use Case | |---|---|---| | exponential | e^(-rate * days) | Smooth, natural decay (default) | | linear | max(1 - rate * days, 0) | Predictable, linear drop-off | | step | 1.0 / 0.7 / 0.4 / 0.1 at 7/30/90 days | Discrete tiers | | none | Always 1.0 | Elephants never forget |

# Fast decay: what happened last week? who cares
ScoringConfig(decay_function=DecayFunction.EXPONENTIAL, decay_rate=0.05)

# Slow decay: memories stay relevant longer
ScoringConfig(decay_function=DecayFunction.EXPONENTIAL, decay_rate=0.005)

# No decay: all memories equally fresh forever
ScoringConfig(decay_function=DecayFunction.NONE)

---

Providers

| Type | Provider | Install | One-line example | |---|---|---|---| | LLM | OpenAI (default) | pip install widemem-ai[faiss] | LLMConfig(provider="openai", model="gpt-4o-mini") | | LLM | Anthropic | pip install widemem-ai[anthropic] | LLMConfig(provider="anthropic", model="claude-haiku-4-5-20251001") | | LLM | Ollama (local) | pip install widemem-ai[ollama] | LLMConfig(provider="ollama", model="llama3") | | Embedding | OpenAI (default) | pip install widemem-ai[faiss] | EmbeddingConfig(provider="openai", model="text-embedding-3-small", dimensions=1536) | | Embedding | Sentence Transformers | pip install widemem-ai[sentence-transformers] | EmbeddingConfig(provider="sentence-transformers", model="all-MiniLM-L6-v2", dimensions=384) | | Vector store | FAISS (default) | pip install widemem-ai[faiss] | `VectorStoreConfi