widemem

  Goldfish memory? ¬_¬ Fixed.

widemem is a local-first memory layer for LLM apps. It extracts facts from conversations, ranks them by importance and recency, resolves contradictions in one LLM call, and tells your agent how confident it is before it answers. By default everything runs on your machine: Ollama for the LLM, sentence-transformers for embeddings, FAISS and SQLite for storage. Cloud providers (OpenAI, Anthropic) are optional add-ons.

Install

pip install "widemem-ai[local]"   # FAISS, Ollama client, sentence-transformers
ollama pull llama3.1:8b           # the default local model, 4.9 GB

You need Ollama installed and running. The first run also downloads the all-MiniLM-L6-v2 embedding model (about 90 MB) from Hugging Face; after that, set HF_HUB_OFFLINE=1 and widemem runs fully offline. Python 3.10+.

What local costs: [local] pulls PyTorch through sentence-transformers (about 550 MB on macOS; more on Linux with CUDA wheels), and each add() makes two LLM calls, extract then resolve. On an Apple M4 with 32 GB, an add() took 5 to 17 seconds and a search 0.04 seconds. The default is llama3.1:8b because llama3.2 (3B) kept the stale fact and split "I'm allergic to penicillin" into one fact per word in every one of our test runs.

Upgrading from 1.6 or earlier: the defaults moved from OpenAI to local, and a 1536-dimension FAISS index will not load under the 384-dimension default embedder. Set provider="openai" on both LLMConfig and EmbeddingConfig to keep the old behavior. Details in the changelog.

Quick start

from widemem import WideMemory, MemoryConfig
from widemem.core.types import VectorStoreConfig

memory = WideMemory(MemoryConfig(
    vector_store=VectorStoreConfig(provider="faiss", path="./widemem_data"),
))

memory.add("I live in San Francisco and work as a software engineer", user_id="alice")
memory.add("I just moved to Boston", user_id="alice")   # checked against stored facts: ADD, UPDATE or DELETE

results = memory.search("where does alice live", user_id="alice")
if results:
    print(results[0].memory.content)                   # results.confidence says how sure it is
    history = memory.get_history(results[0].memory.id) # every write is logged

Without a path, FAISS keeps vectors in RAM and they are gone when the process exits; the SQLite history persists either way. WideMemory also works as a context manager.

Cloud providers, if you want them

No memory, prompt or embedding leaves your machine unless you configure a cloud provider. Each provider picks its own default model.

pip install "widemem-ai[openai,faiss]"      # or [anthropic,local] for Claude + local embeddings

from widemem import WideMemory, MemoryConfig
from widemem.core.types import EmbeddingConfig, LLMConfig

# OpenAI for both: gpt-4o-mini and text-embedding-3-small
memory = WideMemory(MemoryConfig(
    llm=LLMConfig(provider="openai"),
    embedding=EmbeddingConfig(provider="openai"),
))

# Claude for extraction; embeddings and vectors stay local
memory = WideMemory(MemoryConfig(llm=LLMConfig(provider="anthropic")))

Set OPENAI_API_KEY or ANTHROPIC_API_KEY. Mixing is fine: a cloud LLM with local embeddings keeps every vector on your machine.

Every field and default: docs/configuration.md.

How widemem differs

How each one works, with snippets: docs/guide.md. YMYL details and limits: YMYL.md.

Benchmark

On LoCoMo's 1,540 answerable questions (the adversarial category excluded, as for every system on the comparison page), widemem 1.5.0 scored 55.15% with an independent GPT-4o judge (56.32% self-graded), using about 213 tokens of context per query. That run used OpenAI (gpt-4o-mini, text-embedding-3-small) with top_k=10 per speaker; the local default has not been benchmarked yet. It places widemem in the lower half of the eight systems on widemem.ai/benchmarks, at a small fraction of the context most of them use.

Per-category labels published before 2026-07-06 were wrong; the correction is in the corrections log.

The runner (benchmark/run_ws1.py) and question split are in this repo. To re-run it, clone snap-research/locomo into benchmark/locomo-data/ (the runner reads data/locomo10.json) and set OPENAI_API_KEY.

Integrations

MCP server for Claude Desktop, Cursor and other MCP clients. Runs on the local stack by default.

pip install "widemem-ai[mcp,local]"
python -m widemem.mcp_server

Tools exposed: widemem_add, widemem_search, widemem_delete, widemem_count, widemem_pin, widemem_export, widemem_health. Setup and environment variables: docs/mcp.md.

LangChain. widemem.integrations.langchain.WidememRetriever is a BaseRetriever. Install [langchain]; example in examples/langchain_retriever.py.

REST server. pip install "widemem-ai[server,local]", then python -m widemem.server. It refuses to start when WIDEMEM_HOST is non-local and WIDEMEM_API_KEY is unset. The check reads WIDEMEM_HOST, not the bind address, so set it even when you launch uvicorn yourself.

API

Full signatures: docs/api.md.

Scope and safety

widemem is developer infrastructure, provided under Apache 2.0 as is. It is not medical, legal, tax or financial advice, and not a medical device. YMYL handling is a best-effort heuristic, the prompt-injection sanitizer is a baseline defense on extraction input, and the history log does not record callers. Keep a human in the loop for high-stakes decisions. When you self-host, your data stays in your environment and we receive nothing. The software may be subject to export-control and sanctions laws (including the US EAR and OFAC lists).

Roadmap

Open issues; vote with reactions:

• #21 Source-message provenance: link each fact in the history log to the message that produced it
• #22 LangChain BaseChatMessageHistory adapter
• #24 LangGraph BaseStore adapter

Not planned: more vector backends beyond FAISS, Qdrant and pgvector; a hosted multi-tenant service; a web UI; a GraphQL API; a memory-management CLI.

Development

git clone https://github.com/remete618/widemem-ai
cd widemem-ai
pip install -e ".[all,dev]"
pytest

Further reading

• Why Context Windows Aren't Memory
• Your AI Memory Can't Tell a River Bank from a Savings Account
• Your AI Should Know When It Doesn't Know
• Whitepaper: How LLMs Handle Memory

Contact and license

hello@widemem.ai · widemem.ai · issues

Apache 2.0, see LICENSE. Website terms: widemem.ai/terms.