Quickstart

Five minutes from pip install to your first working memory layer. No API keys required if you use the local defaults.

1. Install

pip install "widemem-ai[faiss]"

That pulls the core library plus FAISS for the vector index. The base install ships without FAISS since v1.4.1, so you need the extra (the quotes keep zsh from expanding the brackets). For local embeddings (no API key needed), add the sentence-transformers extra:

pip install "widemem-ai[faiss,sentence-transformers]"

For the Claude Code MCP server and skill integration:

pip install "widemem-ai[faiss,mcp,sentence-transformers]"

2. First add and search

Six lines. One import. No YAML, no setup wizard, no cloud account.

from widemem import WideMemory

memory = WideMemory()

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

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

WideMemory() boots the default pipeline: GPT-4o-mini for fact extraction and conflict resolution, text-embedding-3-small for embeddings, FAISS for the vector index, SQLite for metadata and history. Override any of these via MemoryConfig.

3. Conflict resolution is automatic

Add a contradicting fact and the resolver handles it in a single LLM call. No manual dedup logic, no stale entries.

memory.add("I just moved to Boston", user_id="alice")

# The San Francisco memory gets updated or replaced,
# not silently appended alongside the new one.
results = memory.search("where does alice live", user_id="alice")

4. Pin what must not be forgotten

For facts that should never decay (allergies, API keys, critical safety constraints), use pin():

memory.pin(
    "Allergic to penicillin",
    user_id="alice",
    importance=9.0,
)

Pinned memories start at high importance and resist the decay function. See the YMYL section for the automatic classification that also pins health, financial, and legal facts.

5. Confidence-aware retrieval

Every search() call returns a confidence level so your agent knows whether it has an answer or is guessing.

results = memory.search("what is alice's blood type", user_id="alice")

if results.confidence == "none":
    reply = "I don't have that stored."
elif results.confidence == "high":
    reply = f"Alice's blood type is {results[0].memory.content}"
else:
    reply = "I think so, but I'm not 100% sure."

Four levels: high, moderate, low, none. Set uncertainty_mode on MemoryConfig to control how the system behaves when confidence is low: strict (refuse), helpful (hedge with context), or creative (offer to guess).

6. Context manager for cleanup

Use a with block to guarantee SQLite connections close cleanly. Matters in long-running services and tests.

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.

Next

Configure providers, retrieval modes, and the scoring function: /docs/configuration.

Deploy to production: /docs/self-hosting.

See how widemem scores against Mem0, Zep, and LangMem on the LoCoMo benchmark: /benchmarks.