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

That pulls the core library with FAISS and SQLite. For local embeddings (no API key needed), add the sentence-transformers extra:

pip install widemem-ai[sentence-transformers]

For the Claude Code MCP server and skill integration:

pip install widemem-ai[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.