Metadata-Version: 2.4
Name: forget-rag
Version: 0.1.0
Summary: A forgetting layer for RAG systems — heat-based decay, tiered storage, graceful eviction.
Project-URL: Homepage, https://github.com/zx22413/forget-rag
Project-URL: Repository, https://github.com/zx22413/forget-rag
Project-URL: Documentation, https://github.com/zx22413/forget-rag/blob/main/README.md
Project-URL: Changelog, https://github.com/zx22413/forget-rag/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/zx22413/forget-rag/issues
Author: LBDog
License: MIT
Keywords: forgetting,knowledge-management,llm,memory,rag,retrieval,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Description-Content-Type: text/markdown

# forget-rag

A forgetting layer for RAG systems — heat-based decay, tiered storage,
and graceful eviction so your knowledge base doesn't get dumber over time.

> **Status:** v0.1 (alpha). BM25 + heat ranking, L1/L2/L3 tiers, soft
> delete with restore-ready schema. Vector layer lands in v0.2.

## Install

```bash
pip install forget-rag

# with the LangChain adapter
pip install "forget-rag[langchain]"
```

## Quickstart

```python
from forget_rag import ForgettingMemory

memory = ForgettingMemory(
    backend="sqlite",
    decay_halflife_days=30,
    tiers={"L1": 1000, "L2": 10000, "L3": "unlimited"},
)

memory.add("Some knowledge chunk", tags=["meeting", "2026-Q1"])
results = memory.search("query", limit=5)   # auto-promotes hot chunks
report = memory.health_check()              # what should be forgotten?
```

## What's in the box

- **Heat score** — every chunk has a decay function based on access
  frequency + recency.
- **L1 / L2 / L3 tiers** — modeled after CPU cache; hot stays in vector
  + FTS, warm in FTS only, cold is archived but searchable.
- **Soft delete** — `forget()` flags rather than drops; v0.2 will expose
  `restore()` on top of the existing `forgotten_at` column.
- **LangChain adapter** — `ForgettingRetriever` extends `BaseRetriever`
  for drop-in chain use.

## Companion CLI

The [`mem-broom`](https://github.com/zx22413/forget-rag/tree/main/packages/mem-broom)
companion package wraps this library with a typer-based CLI for ad-hoc
memory hygiene. v0.1 ships it as a git install (the PyPI publish is
deferred — see the project README for the install command).

## Links

- Repo: https://github.com/zx22413/forget-rag
- Benchmark write-up: https://github.com/zx22413/forget-rag/blob/main/docs/benchmark.md
- Architecture: https://github.com/zx22413/forget-rag/blob/main/docs/architecture.md
- Issues: https://github.com/zx22413/forget-rag/issues

## License

MIT.
