Metadata-Version: 2.4
Name: memgov
Version: 0.1.0
Summary: Provider-agnostic governance layer for AI agent memory: reuse-aware decay, confidence-gated recall injection, and memory-health metrics. Governs the memory you already have (mem0/Zep/vector DB) instead of storing it.
Author: wangkevin2100-cell
License: MIT
Project-URL: Homepage, https://github.com/wangkevin2100-cell/memgov
Project-URL: Repository, https://github.com/wangkevin2100-cell/memgov
Keywords: llm,ai-agents,memory,rag,decay,context,governance,mem0,zep
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Dynamic: license-file

# memgov

> Provider-agnostic **governance layer** for AI agent memory. It doesn't store
> your memory — it governs the memory you already have (mem0 / Zep / a raw
> vector DB): decays it by recency × reuse, gates recall injection behind a
> confidence threshold so stale junk never reaches the prompt, and surfaces
> memory-health metrics. Local-first (SQLite), zero required deps, BYO store.

## The problem

The 2025–2026 memory stores (mem0, Zep, LangMem, Letta) solved *write* and
*retrieve*. But after a quarter of accumulation, teams hit the second-order
problem: **memory useful in week 1 is actively harmful in week 12, and nothing
ages it out.** Stores answer "what do I remember?" — none answer "what should I
have *forgotten*, and what's safe to inject right now?" That's governance, and
it's missing.

memgov fills that lane:

- **Reuse-aware decay** — a tunable `recency × reuse` score, not a crude global TTL.
- **Confidence-gated recall** — always search, but only *inject* when retrieval
  confidence clears a threshold and the memory isn't stale.
- **Memory health** — `active / fading / stale` ratios so silent degradation
  becomes observable *before* answers get bad.

## Install

```bash
pip install memgov        # zero required deps
```

Python 3.11+.

## Quick start

```python
from memgov import Governor, Candidate

gov = Governor()                              # local SQLite sidecar

# register memories your store already holds, keyed by the store's native id
gov.track("mem-1", agent_id="bot")
gov.reinforce("mem-1", agent_id="bot")        # user restated it -> reinforce

gov.recompute(agent_id="bot")                 # recompute decay scores + states

# on recall: your store returns candidates; memgov gates what actually injects
candidates = [Candidate("mem-1", confidence=0.82),
              Candidate("mem-9", confidence=0.31)]   # low-confidence
inject = gov.gate(candidates, agent_id="bot")        # only the worthy ones
print([c.mem_id for c in inject])             # -> ['mem-1']

print(gov.health(agent_id="bot"))             # active/fading/stale snapshot
```

## How it works

- **Sidecar metadata** keyed by your store's native `mem_id` (memgov never holds
  the memory text — it tracks the signals decay needs).
- **`track / touch / reinforce`** record usage signals; `reinforce` (user
  restated/confirmed) is the strongest keep signal.
- **`recompute`** rescans an agent's memories and assigns `decay_score` (0..1)
  and a `state`: `active | fading | stale | pinned`.
- **`gate`** is the core: it receives recall candidates and passes only those
  with confidence ≥ threshold **and** not `stale`. `pin` protects a memory from
  ever decaying.

## See it (no deps, no API key)

```bash
python examples/demo_governance.py
```

## Status

Early MVP (v0.1). Implemented: decay scorer, gate middleware, health metrics,
SQLite sidecar, CLI. Planned: store adapters (mem0/Zep), MCP-server option,
embedding-confidence helpers, health dashboard.

## License

MIT.
