# widemem-ai

> Local-first, open-source memory layer for LLM apps and agents: importance scoring, temporal decay, batch conflict resolution, and confidence-aware retrieval. Runs offline on Ollama, sentence-transformers, FAISS and SQLite by default; OpenAI and Anthropic are optional. Python 3.10+.

widemem gives an AI persistent memory. It extracts facts from text, stores them in a vector store, resolves contradictions automatically, decays stale memories over time, and returns ranked, confidence-scored results. The defaults run entirely on your machine.

Install and run:

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

```python
from widemem import WideMemory

memory = WideMemory()
memory.add("I live in San Francisco and work as a software engineer", user_id="alice")
results = memory.search("where does alice live", user_id="alice")
for r in results:
    print(r.memory.content, round(r.final_score, 2))

# New facts are checked against stored ones in one LLM call (ADD, UPDATE or DELETE):
memory.add("I just moved to Boston", user_id="alice")
```

`WideMemory()` defaults to Ollama (`llama3.1:8b`) for the LLM, sentence-transformers (`all-MiniLM-L6-v2`) for embeddings, and FAISS plus SQLite for storage; no API key needed. Without a FAISS `path`, vectors live in RAM. To use OpenAI or Anthropic, install the `[openai]` or `[anthropic]` extra and set `LLMConfig(provider=...)` / `EmbeddingConfig(provider=...)`.

## Start here
- [README](README.md): full overview, features, and install matrix
- [Quick start](README.md#quick-start): the working example
- [Install](README.md#install): the `[local]` stack; cloud providers are optional extras

## Docs
- [Configuration](docs/configuration.md): every config field, its default, and the tradeoff
- [API reference](docs/api.md): WideMemory methods and the core types
- [MCP server](docs/mcp.md): run widemem as a Model Context Protocol server for agents

## Concepts
- [Scoring and decay](docs/guide.md#scoring--decay): the ranking formula and decay functions
- [YMYL prioritization](docs/guide.md#ymyl-your-money-or-your-life): two-stage semantic classification for high-stakes facts
- [Hierarchical memory and tiers](docs/guide.md#hierarchical-memory): summarization and memory tiers
- [Temporal search](docs/guide.md#temporal-search): time-aware retrieval and boosts
- [Uncertainty and confidence](docs/guide.md#uncertainty--confidence): confidence modes and frustration recovery
- [Batch conflict resolution](docs/guide.md#batch-conflict-resolution): single-call ADD/UPDATE/DELETE resolution
- [Prompt-injection sanitizer](docs/guide.md#prompt-injection-sanitizer): input sanitization for stored content

## Examples
- [basic_usage.py](examples/basic_usage.py): add and search
- [hierarchical_memory.py](examples/hierarchical_memory.py): tiers and summarization
- [temporal_queries.py](examples/temporal_queries.py): time-aware search
- [ymyl_active_retrieval.py](examples/ymyl_active_retrieval.py): YMYL plus active retrieval
- [healthcare_quickstart.py](examples/healthcare_quickstart.py): a domain example

## Optional
- [Development](README.md#development): running tests and contributing
