# Widemem Ai > Next-gen AI memory layer with importance scoring, temporal decay, hierarchical memory, and YMYL prioritization - **Type:** MCP server - **Install:** `agentstack add mcp-remete618-widemem-ai` - **Verified:** Pending review - **Seller:** [remete618](https://agentstack.voostack.com/s/remete618) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [remete618](https://github.com/remete618) - **Source:** https://github.com/remete618/widemem-ai - **Website:** https://widemem.ai ## Install ```sh agentstack add mcp-remete618-widemem-ai ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # widemem.ai ``` .__ .___ .__ __ _ _|__| __| _/____ _____ ____ _____ _____ |__| \ \/ \/ / |/ __ |/ __ \ / \_/ __ \ / \ \__ \ | | \ /| / /_/ \ ___/| Y Y \ ___/| Y Y \ / __ \| | \/\_/ |__\____ |\___ >__|_| /\___ >__|_| / /\ (____ /__| \/ \/ \/ \/ \/ \/ \/ ``` >   *Goldfish memory? ¬_¬ Fixed.* [](https://pypi.org/project/widemem-ai/) [](https://pypi.org/project/widemem-ai/) [](https://github.com/remete618/widemem-ai/actions/workflows/ci.yml) [](https://scorecard.dev/viewer/?uri=github.com/remete618/widemem-ai) [](LICENSE) [](https://python.org) **Background reading:** - [Whitepaper: How LLMs Handle Memory](https://github.com/remete618/llm-memory-whitepaper). Technical paper on memory architectures, security risks, and in-weights personalisation. - [Why Context Windows Aren't Memory](https://widemem.ai/blog/context-windows). The problem widemem solves. - [Your AI Memory Can't Tell a River Bank from a Savings Account](https://widemem.ai/blog/semantic-ymyl). How YMYL classification actually works. - [Your AI Should Know When It Doesn't Know](https://widemem.ai/blog/uncertainty). Uncertainty-aware retrieval. ### 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 ↗](https://widemem.ai/blog/semantic-ymyl) - **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 --- ## 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. | 380+ 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](#install) - [Quick Start](#quick-start) - [Configuration](#configuration) - [Scoring & Decay](#scoring--decay) - [Providers](#providers) - [YMYL (Your Money or Your Life)](#ymyl-your-money-or-your-life) - [Hierarchical Memory](#hierarchical-memory) - [Active Retrieval](#active-retrieval) - [Temporal Search](#temporal-search) - [Uncertainty & Confidence](#uncertainty--confidence) - [Retrieval Modes](#retrieval-modes) - [History & Audit Trail](#history--audit-trail) - [Batch Conflict Resolution](#batch-conflict-resolution) - [Prompt-Injection Sanitizer](#prompt-injection-sanitizer) - [API Reference](#api-reference) - [Claude Code Skill](#claude-code-skill) - [MCP Server](#mcp-server) - [Development](#development) - [Terms & Conditions](#terms--conditions) - [Contact](#contact) - [License](#license) --- ## Install ```bash 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 ```bash 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. ```python 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: ```python 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: ```python 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](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 | ```python # 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]` | `VectorStoreConfig(provider="faiss")` | | Vector store | Qdrant | `pip install widemem-ai[qdrant]` | `VectorStoreConfig(provider="qdrant", path="./qdrant_data")` | For Ollama, pair with sentence-transformers if you want fully local: `EmbeddingConfig(provider="sentence-transformers", model="all-MiniLM-L6-v2", dimensions=384)`. Set `QDRANT_URL` env var for remote Qdrant. --- ## YMYL (Your Money or Your Life) Some facts are more equal than others. YMYL prioritization ensures that critical facts about health, finances, legal matters, and safety are never lost, never deprioritized, and never quietly forgotten because the decay function decided Tuesday was a good day to forget someone's insulin dosage. > For the full deep dive on how YMYL works, edge cases, and limitations, see **[YMYL.md](YMYL.md)**. ```python config = MemoryConfig( ymyl=YMYLConfig( enabled=True, categories=["health", "medical", "financial", "legal", "safety", "insurance", "tax", "pharmaceutical"], min_importance=8.0, # Floor importance for strong YMYL facts decay_immune=True, # Strong YMYL facts don't decay over time force_active_retrieval=True, # Force contradiction detection for strong YMYL facts ), ) ``` ### Two-Stage Semantic Classification Not every mention of "bank" means someone's talking about their finances. And "my chest has been hurting for three days" is a health concern even though it contains no medical keyword. widemem uses a **two-stage pipeline** to handle both cases: | Stage | How it works | Example | |---|---|---| | **1. Regex (fast)** | Multi-word strong patterns fire immediately | "blood pressure" -> health, "401k" -> financial | | **2. LLM (semantic)** | LLM classifies during fact extraction (zero extra API calls) | "my chest hurts" -> health, "bank of the river" -> null | Strong regex matches get immediate YMYL protection. For everything else, the LLM decides based on context. This catches implied YMYL content ("I stopped taking my pills" -> medical) and rejects false positives ("The Doctor is a great TV show" -> not medical). > For the full breakdown with accuracy data and examples, see **[Your AI Memory Can't Tell a River Bank from a Savings Account](https://widemem.ai/blog/semantic-ymyl)**. | Classification | Importance | Decay immunity | Active retrieval | |---|---|---|---| | **YMYL (regex or LLM)** | Floor at 8.0 | Yes | Forced | | **Not YMYL** | Unchanged | No | No | ### YMYL Categories 8 categories, each with strong (unambiguous) and weak (context-dependent) patterns: | Category | Strong Patterns | Weak Patterns | |---|---|---| | `health` | blood pressure, diabetes diagnosis, mental health | doctor, hospital, medication, anxiety | | `medical` | lab results, medical condition, treatment plan | clinic, vaccine, MRI, scan | | `financial` | bank account, savings account, credit score, 401k | bank, loan, debt, salary | | `legal` | power of attorney, child custody, court order | lawyer, contract, divorce | | `safety` | emergency contact, blood type, epipen, DNR order | evacuation, flood | | `insurance` | insurance policy, insurance premium | insurance, coverage, claim | | `tax` | tax return, W-2, 1099, IRS audit | deduction, filing | | `pharmaceutical` | side effect, drug interaction | drug, dosage, prescription | You can enable a subset if you only care about some categories: ```python YMYLConfig(enabled=True, categories=["health", "medical", "financial"]) ``` ### Topic Weights (related) Boost or suppress specific topics during retrieval as a multiplier on `final_score`: ```python config = MemoryConfig( topics=TopicConfig( weights={"python": 2.0, "cooking": 0.5}, custom_topics=["python", "machine learning"], # Extraction hints ), ) ``` Matching is case-insensitive substring. Values above 1.0 boost, below 1.0 suppress. `custom_topics` are passed to the LLM during extraction as a hint. --- ## Hierarchical Memory Three-tier memory system. Facts are great, but sometimes you need the big picture. ```python config = MemoryConfig(enable_hierarchy=True) memory = WideMemory(config) # Add many facts for msg in conversation_history: memory.add(msg, user_id="alice") # Trigger summarization (groups related facts, creates summaries and themes) memory.summarize(user_id="alice") # Broad queries return themes, specific queries return facts results = memory.search("tell me about alice") # Returns themes results = memory.search("where does alice live") # Returns facts # Filter by tier from widemem.core.types import MemoryTier results = memory.search("alice", tier=MemoryTier.SUMMARY) ``` ### Tiers | Tier | Description | Query Type | |---|---|---| | `fact` | Individual extracted f … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [remete618](https://github.com/remete618) - **Source:** [remete618/widemem-ai](https://github.com/remete618/widemem-ai) - **License:** Apache-2.0 - **Homepage:** https://widemem.ai Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-remete618-widemem-ai - Seller: https://agentstack.voostack.com/s/remete618 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.