memgov 0.1.0__tar.gz

memgov-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangkevin2100-cell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memgov-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+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.

memgov-0.1.0/README.md

@@ -0,0 +1,82 @@
+# 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.

memgov-0.1.0/memgov/__init__.py

@@ -0,0 +1,40 @@
+"""memgov — provider-agnostic governance layer for AI agent memory.
+
+不存储记忆，而是治理你已有的记忆（mem0 / Zep / 向量库）：
+  - 按 recency × reuse 衰减，让陈旧记忆自然淡出
+  - 召回时按置信度门控注入，陈旧垃圾不进 prompt
+  - 出"记忆健康度"指标，让静默退化变可观测
+
+Quick start::
+
+    from memgov import Governor, Candidate
+
+    gov = Governor()
+    gov.track("mem-1", agent_id="bot")        # 登记一条记忆进治理层
+    gov.reinforce("mem-1", agent_id="bot")     # 用户重申 -> 强化保留
+
+    gov.recompute(agent_id="bot")              # 重算衰减分 + 状态
+    # 召回时门控：只放行置信度够且没陈旧的
+    keep = gov.gate([Candidate("mem-1", confidence=0.8)], agent_id="bot")
+    print(gov.health(agent_id="bot"))
+"""
+from __future__ import annotations
+
+from .decay import decay_score, recency_factor, reuse_bonus
+from .governor import Governor
+from .models import Candidate, HealthReport, MemoryMeta, MemoryState
+from .store import MetaStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Governor",
+    "MetaStore",
+    "MemoryMeta",
+    "MemoryState",
+    "Candidate",
+    "HealthReport",
+    "decay_score",
+    "recency_factor",
+    "reuse_bonus",
+]

memgov-0.1.0/memgov/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

memgov-0.1.0/memgov/cli.py

@@ -0,0 +1,42 @@
+"""memgov CLI：查看记忆健康度、重算衰减。
+
+用法:
+  memgov health [--agent NAME] [--db PATH]   查看健康度
+  memgov recompute [--agent NAME] [--db PATH]  重算衰减分+状态
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .governor import Governor
+from .store import MetaStore
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="memgov")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    for name in ("health", "recompute"):
+        sp = sub.add_parser(name)
+        sp.add_argument("--agent", default="default")
+        sp.add_argument("--db", default=".memgov/memgov.db")
+
+    args = p.parse_args(argv)
+    gov = Governor(store=MetaStore(args.db))
+
+    if args.cmd == "recompute":
+        n = gov.recompute(agent_id=args.agent)
+        print(f"recomputed {n} memories for agent '{args.agent}'")
+        return 0
+    if args.cmd == "health":
+        h = gov.health(agent_id=args.agent)
+        print(f"agent={h.agent_id} total={h.total} active={h.active} "
+              f"fading={h.fading} stale={h.stale} pinned={h.pinned} "
+              f"stale_ratio={h.stale_ratio:.2f} avg_score={h.avg_decay_score:.3f}")
+        return 0
+    p.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

memgov-0.1.0/memgov/decay.py

@@ -0,0 +1,45 @@
+"""衰减评分：recency（时间新近）× reuse（复用/强化）。
+
+这是 memgov 的核心——决定一条记忆"现在还该不该算数"。纯函数，无副作用，
+便于属性测试。返回 [0,1] 的分数：越高 = 越该保留并参与注入。
+
+设计：
+- recency：自上次访问起按半衰期指数衰减。越久没碰，分越低。
+- reuse：访问/强化越多，越该保留——给一个有上限的加成（防止被刷爆）。
+- pinned 由上层处理（钉住的不走衰减）。
+"""
+from __future__ import annotations
+
+import math
+
+# 默认参数（可调）
+DEFAULT_HALF_LIFE_DAYS = 14.0     # 14 天没访问，recency 减半
+REINFORCE_BONUS = 0.15            # 每次强化的加成
+MAX_REUSE_BONUS = 0.5             # reuse 加成上限
+_SECONDS_PER_DAY = 86400.0
+
+
+def recency_factor(age_seconds: float, half_life_days: float = DEFAULT_HALF_LIFE_DAYS) -> float:
+    """自上次访问的时间衰减因子，∈ (0, 1]。age=0 -> 1.0，越久越接近 0。"""
+    if age_seconds <= 0:
+        return 1.0
+    half_life_seconds = max(half_life_days, 1e-9) * _SECONDS_PER_DAY
+    return math.pow(0.5, age_seconds / half_life_seconds)
+
+
+def reuse_bonus(access_count: int, reinforce_count: int) -> float:
+    """复用加成，∈ [0, MAX_REUSE_BONUS]。强化比普通访问权重高。"""
+    raw = REINFORCE_BONUS * reinforce_count + 0.02 * max(access_count, 0)
+    return min(max(raw, 0.0), MAX_REUSE_BONUS)
+
+
+def decay_score(
+    age_seconds: float,
+    access_count: int = 0,
+    reinforce_count: int = 0,
+    half_life_days: float = DEFAULT_HALF_LIFE_DAYS,
+) -> float:
+    """综合衰减分，∈ [0,1]。recency 为基底，reuse 在其上加成后截断到 1。"""
+    base = recency_factor(age_seconds, half_life_days)
+    score = base + reuse_bonus(access_count, reinforce_count) * base
+    return min(max(score, 0.0), 1.0)

memgov-0.1.0/memgov/governor.py

@@ -0,0 +1,137 @@
+"""Governor：记忆治理中间件主类。
+
+套在你已有的记忆存储前面，做三件事（spec 的三大核心）：
+  1. 衰减治理：track/touch/reinforce 记录信号，recompute 按 recency×reuse 重算分数+状态
+  2. 召回门控：gate() 总是接收存储召回的候选，但只放行"置信度够 + 没陈旧"的注入
+  3. 健康度：health() 出 active/fading/stale 比例，让"静默退化"变可观测
+它不替你存记忆，只治理你已有的记忆。
+"""
+from __future__ import annotations
+
+import time
+
+from .decay import DEFAULT_HALF_LIFE_DAYS, decay_score
+from .models import Candidate, HealthReport, MemoryMeta, MemoryState
+from .store import MetaStore
+
+
+class Governor:
+    def __init__(
+        self,
+        store: MetaStore | None = None,
+        *,
+        half_life_days: float = DEFAULT_HALF_LIFE_DAYS,
+        active_threshold: float = 0.5,   # >= 视为 active
+        fading_threshold: float = 0.2,   # >= 视为 fading，否则 stale
+        min_confidence: float = 0.6,     # 召回注入的默认置信度门槛
+    ):
+        self.store = store or MetaStore()
+        self.half_life_days = half_life_days
+        self.active_threshold = active_threshold
+        self.fading_threshold = fading_threshold
+        self.min_confidence = min_confidence
+
+    # ---- 记录治理信号 ----
+    def track(self, mem_id: str, *, agent_id: str = "default",
+              source: str = "user_msg", now: float | None = None) -> MemoryMeta:
+        """登记一条新记忆进治理层。"""
+        t = now if now is not None else time.time()
+        m = MemoryMeta(mem_id=mem_id, agent_id=agent_id, created_utc=t,
+                       last_access_utc=t, access_count=0, reinforce_count=0,
+                       decay_score=1.0, state=MemoryState.ACTIVE,
+                       source=source, last_eval_utc=t)
+        self.store.upsert(m)
+        return m
+
+    def touch(self, mem_id: str, *, agent_id: str = "default",
+              now: float | None = None) -> None:
+        """记忆被召回/读取——更新访问时间和计数。"""
+        m = self.store.get(mem_id, agent_id)
+        if m is None:
+            m = self.track(mem_id, agent_id=agent_id, now=now)
+        m.last_access_utc = now if now is not None else time.time()
+        m.access_count += 1
+        self.store.upsert(m)
+
+    def reinforce(self, mem_id: str, *, agent_id: str = "default",
+                  now: float | None = None) -> None:
+        """记忆被显式强化（用户重申/确认）——最强的保留信号。"""
+        m = self.store.get(mem_id, agent_id)
+        if m is None:
+            m = self.track(mem_id, agent_id=agent_id, now=now)
+        m.reinforce_count += 1
+        m.last_access_utc = now if now is not None else time.time()
+        self.store.upsert(m)
+
+    def pin(self, mem_id: str, *, agent_id: str = "default") -> None:
+        m = self.store.get(mem_id, agent_id)
+        if m:
+            m.state = MemoryState.PINNED
+            self.store.upsert(m)
+
+    # ---- 重算衰减 ----
+    def recompute(self, *, agent_id: str = "default", now: float | None = None) -> int:
+        """重算某 agent 所有记忆的 decay_score 和 state。返回处理条数。"""
+        t = now if now is not None else time.time()
+        metas = self.store.list_for_agent(agent_id)
+        for m in metas:
+            if m.state == MemoryState.PINNED:
+                continue
+            age = max(t - m.last_access_utc, 0.0)
+            m.decay_score = decay_score(age, m.access_count, m.reinforce_count,
+                                        self.half_life_days)
+            m.state = self._state_for(m.decay_score)
+            m.last_eval_utc = t
+            self.store.upsert(m)
+        return len(metas)
+
+    def _state_for(self, score: float) -> MemoryState:
+        if score >= self.active_threshold:
+            return MemoryState.ACTIVE
+        if score >= self.fading_threshold:
+            return MemoryState.FADING
+        return MemoryState.STALE
+
+    # ---- 召回门控（核心价值）----
+    def gate(self, candidates: list[Candidate], *, agent_id: str = "default",
+             min_confidence: float | None = None,
+             include_fading: bool = True) -> list[Candidate]:
+        """门控召回注入：总是接收候选，但只放行该注入的。
+
+        规则：置信度 >= 门槛 且 状态不是 stale（fading 可选放行）。
+        chosen 的会顺便 touch（被注入即被使用）。
+        """
+        thr = min_confidence if min_confidence is not None else self.min_confidence
+        chosen: list[Candidate] = []
+        for c in candidates:
+            if c.confidence < thr:
+                continue
+            m = self.store.get(c.mem_id, agent_id)
+            state = m.state if m else MemoryState.ACTIVE
+            if state == MemoryState.STALE:
+                continue
+            if state == MemoryState.FADING and not include_fading:
+                continue
+            chosen.append(c)
+        for c in chosen:
+            self.touch(c.mem_id, agent_id=agent_id)
+        return chosen
+
+    # ---- 健康度 ----
+    def health(self, *, agent_id: str = "default") -> HealthReport:
+        metas = self.store.list_for_agent(agent_id)
+        rep = HealthReport(agent_id=agent_id, total=len(metas))
+        if not metas:
+            return rep
+        for m in metas:
+            if m.state == MemoryState.ACTIVE:
+                rep.active += 1
+            elif m.state == MemoryState.FADING:
+                rep.fading += 1
+            elif m.state == MemoryState.STALE:
+                rep.stale += 1
+            elif m.state == MemoryState.PINNED:
+                rep.pinned += 1
+        rep.stale_ratio = rep.stale / rep.total
+        rep.avg_decay_score = sum(m.decay_score for m in metas) / rep.total
+        return rep

memgov-0.1.0/memgov/models.py

@@ -0,0 +1,52 @@
+"""数据模型：每条被治理记忆的 sidecar 元数据。
+
+memgov 不存储记忆本身——它在你已有的记忆存储（mem0/Zep/向量库）旁边，
+按存储原生的 mem_id 镜像一份"治理信号"，用来算衰减、决定注入、出健康度。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class MemoryState(str, Enum):
+    ACTIVE = "active"     # 活跃，正常参与召回注入
+    FADING = "fading"     # 在衰退，注入需更高置信度
+    STALE = "stale"       # 陈旧，默认不注入（除非显式）
+    PINNED = "pinned"     # 钉住，永不衰减/永不 stale
+
+
+@dataclass
+class MemoryMeta:
+    """一条记忆的治理元数据（对应 spec 的 sidecar schema）。"""
+    mem_id: str                       # 存储原生 id
+    agent_id: str = "default"
+    created_utc: float = 0.0
+    last_access_utc: float = 0.0
+    access_count: int = 0             # 被召回/读取次数
+    reinforce_count: int = 0          # 被显式强化（用户重申/确认）次数
+    decay_score: float = 1.0          # 0..1，越高越该保留
+    state: MemoryState = MemoryState.ACTIVE
+    source: str = "user_msg"          # user_msg | tool_result | summary
+    last_eval_utc: float = 0.0
+
+
+@dataclass
+class Candidate:
+    """一次召回返回的候选记忆：存储给的 id + 相似度/置信度。"""
+    mem_id: str
+    confidence: float                 # 召回置信度（如向量相似度 0..1）
+    text: str = ""
+
+
+@dataclass
+class HealthReport:
+    """记忆健康度快照。"""
+    agent_id: str
+    total: int = 0
+    active: int = 0
+    fading: int = 0
+    stale: int = 0
+    pinned: int = 0
+    stale_ratio: float = 0.0          # stale / total，越高越该清理
+    avg_decay_score: float = 0.0

memgov-0.1.0/memgov/store.py

@@ -0,0 +1,88 @@
+"""SQLite 持久化：记忆治理元数据的 sidecar 存储。本地优先，零外部依赖。"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from .models import MemoryMeta, MemoryState
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS memory_meta (
+    mem_id          TEXT NOT NULL,
+    agent_id        TEXT NOT NULL DEFAULT 'default',
+    created_utc     REAL DEFAULT 0,
+    last_access_utc REAL DEFAULT 0,
+    access_count    INTEGER DEFAULT 0,
+    reinforce_count INTEGER DEFAULT 0,
+    decay_score     REAL DEFAULT 1.0,
+    state           TEXT DEFAULT 'active',
+    source          TEXT DEFAULT 'user_msg',
+    last_eval_utc   REAL DEFAULT 0,
+    PRIMARY KEY (agent_id, mem_id)
+);
+CREATE INDEX IF NOT EXISTS idx_meta_agent_state ON memory_meta(agent_id, state);
+"""
+
+
+class MetaStore:
+    """治理元数据的 SQLite 存储。"""
+
+    def __init__(self, db_path: str | Path = ".memgov/memgov.db"):
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init()
+
+    def _conn(self) -> sqlite3.Connection:
+        c = sqlite3.connect(str(self.db_path))
+        c.row_factory = sqlite3.Row
+        return c
+
+    def _init(self) -> None:
+        with self._conn() as c:
+            c.executescript(_SCHEMA)
+
+    def upsert(self, m: MemoryMeta) -> None:
+        with self._conn() as c:
+            c.execute(
+                """INSERT INTO memory_meta
+                   (mem_id, agent_id, created_utc, last_access_utc, access_count,
+                    reinforce_count, decay_score, state, source, last_eval_utc)
+                   VALUES (?,?,?,?,?,?,?,?,?,?)
+                   ON CONFLICT(agent_id, mem_id) DO UPDATE SET
+                     created_utc=excluded.created_utc,
+                     last_access_utc=excluded.last_access_utc,
+                     access_count=excluded.access_count,
+                     reinforce_count=excluded.reinforce_count,
+                     decay_score=excluded.decay_score,
+                     state=excluded.state,
+                     source=excluded.source,
+                     last_eval_utc=excluded.last_eval_utc""",
+                (m.mem_id, m.agent_id, m.created_utc, m.last_access_utc,
+                 m.access_count, m.reinforce_count, m.decay_score,
+                 m.state.value, m.source, m.last_eval_utc),
+            )
+
+    def get(self, mem_id: str, agent_id: str = "default") -> MemoryMeta | None:
+        with self._conn() as c:
+            r = c.execute(
+                "SELECT * FROM memory_meta WHERE agent_id=? AND mem_id=?",
+                (agent_id, mem_id),
+            ).fetchone()
+        return _row_to_meta(r) if r else None
+
+    def list_for_agent(self, agent_id: str = "default") -> list[MemoryMeta]:
+        with self._conn() as c:
+            rows = c.execute(
+                "SELECT * FROM memory_meta WHERE agent_id=?", (agent_id,)
+            ).fetchall()
+        return [_row_to_meta(r) for r in rows]
+
+
+def _row_to_meta(r: sqlite3.Row) -> MemoryMeta:
+    return MemoryMeta(
+        mem_id=r["mem_id"], agent_id=r["agent_id"],
+        created_utc=r["created_utc"], last_access_utc=r["last_access_utc"],
+        access_count=r["access_count"], reinforce_count=r["reinforce_count"],
+        decay_score=r["decay_score"], state=MemoryState(r["state"]),
+        source=r["source"], last_eval_utc=r["last_eval_utc"],
+    )

memgov-0.1.0/memgov.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+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.

memgov-0.1.0/memgov.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+memgov/__init__.py
+memgov/__main__.py
+memgov/cli.py
+memgov/decay.py
+memgov/governor.py
+memgov/models.py
+memgov/store.py
+memgov.egg-info/PKG-INFO
+memgov.egg-info/SOURCES.txt
+memgov.egg-info/dependency_links.txt
+memgov.egg-info/entry_points.txt
+memgov.egg-info/requires.txt
+memgov.egg-info/top_level.txt
+tests/test_decay.py
+tests/test_governor.py

memgov-0.1.0/memgov.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

memgov-0.1.0/memgov.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memgov = memgov.cli:main

memgov-0.1.0/memgov.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8.0
+hypothesis>=6.0

memgov-0.1.0/memgov.egg-info/top_level.txt

@@ -0,0 +1 @@
+memgov

memgov-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "memgov"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "wangkevin2100-cell" }]
+keywords = ["llm", "ai-agents", "memory", "rag", "decay", "context", "governance", "mem0", "zep"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "hypothesis>=6.0"]
+
+[project.scripts]
+memgov = "memgov.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/wangkevin2100-cell/memgov"
+Repository = "https://github.com/wangkevin2100-cell/memgov"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["memgov*"]

memgov-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

memgov-0.1.0/tests/test_decay.py

@@ -0,0 +1,56 @@
+"""decay 评分的单元测试 + 正确性属性。"""
+from __future__ import annotations
+
+from hypothesis import given, settings
+from hypothesis import strategies as st
+
+from memgov.decay import decay_score, recency_factor, reuse_bonus
+
+_DAY = 86400.0
+
+
+# Feature: memgov, Property: decay_score 永远落在 [0, 1]
+@settings(max_examples=200)
+@given(
+    age=st.floats(min_value=0, max_value=10_000 * _DAY, allow_nan=False),
+    acc=st.integers(min_value=0, max_value=10_000),
+    rein=st.integers(min_value=0, max_value=10_000),
+)
+def test_score_in_unit_interval(age, acc, rein):
+    s = decay_score(age, acc, rein)
+    assert 0.0 <= s <= 1.0
+
+
+# Feature: memgov, Property: 其它不变时，越久没访问分越低（recency 单调）
+@settings(max_examples=100)
+@given(
+    age1=st.floats(min_value=0, max_value=100 * _DAY),
+    extra=st.floats(min_value=1.0, max_value=100 * _DAY),
+)
+def test_recency_monotonic(age1, extra):
+    assert recency_factor(age1) >= recency_factor(age1 + extra) - 1e-12
+
+
+# Feature: memgov, Property: 强化越多，保留分不降（reuse 单调不减）
+@settings(max_examples=100)
+@given(
+    age=st.floats(min_value=0, max_value=30 * _DAY),
+    rein=st.integers(min_value=0, max_value=50),
+)
+def test_reinforce_does_not_decrease_score(age, rein):
+    s_low = decay_score(age, 0, rein)
+    s_high = decay_score(age, 0, rein + 1)
+    assert s_high >= s_low - 1e-12
+
+
+def test_fresh_memory_scores_high():
+    assert decay_score(0) == 1.0
+
+
+def test_old_unused_memory_decays():
+    # 一年没碰、没复用 -> 应该很低
+    assert decay_score(365 * _DAY) < 0.05
+
+
+def test_reuse_bonus_capped():
+    assert reuse_bonus(10_000, 10_000) <= 0.5

memgov-0.1.0/tests/test_governor.py

@@ -0,0 +1,74 @@
+"""Governor 中间件测试：衰减治理、召回门控、健康度。"""
+from __future__ import annotations
+
+import pytest
+
+from memgov import Candidate, Governor, MemoryState
+from memgov.store import MetaStore
+
+_DAY = 86400.0
+
+
+@pytest.fixture
+def gov(tmp_path):
+    return Governor(store=MetaStore(tmp_path / "t.db"))
+
+
+def test_track_and_get(gov):
+    gov.track("m1", agent_id="bot", now=1000.0)
+    m = gov.store.get("m1", "bot")
+    assert m is not None and m.state == MemoryState.ACTIVE
+
+
+def test_unused_memory_goes_stale_after_recompute(gov):
+    gov.track("old", agent_id="bot", now=0.0)
+    # 一年后重算，没访问没强化 -> stale
+    gov.recompute(agent_id="bot", now=365 * _DAY)
+    assert gov.store.get("old", "bot").state == MemoryState.STALE
+
+
+def test_reinforced_memory_stays_active(gov):
+    gov.track("keep", agent_id="bot", now=0.0)
+    for _ in range(5):
+        gov.reinforce("keep", agent_id="bot", now=300 * _DAY)
+    gov.recompute(agent_id="bot", now=300 * _DAY)
+    assert gov.store.get("keep", "bot").state != MemoryState.STALE
+
+
+def test_pinned_never_decays(gov):
+    gov.track("pin", agent_id="bot", now=0.0)
+    gov.pin("pin", agent_id="bot")
+    gov.recompute(agent_id="bot", now=10_000 * _DAY)
+    assert gov.store.get("pin", "bot").state == MemoryState.PINNED
+
+
+# 核心价值：召回门控
+def test_gate_blocks_low_confidence(gov):
+    gov.track("m1", agent_id="bot", now=1000.0)
+    kept = gov.gate([Candidate("m1", confidence=0.3)], agent_id="bot",
+                    min_confidence=0.6)
+    assert kept == []  # 置信度不够，不注入
+
+
+def test_gate_blocks_stale(gov):
+    gov.track("s1", agent_id="bot", now=0.0)
+    gov.recompute(agent_id="bot", now=365 * _DAY)   # 变 stale
+    kept = gov.gate([Candidate("s1", confidence=0.99)], agent_id="bot")
+    assert kept == []  # 置信度高但已陈旧，仍不注入
+
+
+def test_gate_passes_good_candidate(gov):
+    gov.track("good", agent_id="bot", now=1000.0)
+    gov.recompute(agent_id="bot", now=1000.0)
+    kept = gov.gate([Candidate("good", confidence=0.9)], agent_id="bot")
+    assert [c.mem_id for c in kept] == ["good"]
+
+
+def test_health_counts(gov):
+    gov.track("a", agent_id="bot", now=0.0)
+    gov.track("b", agent_id="bot", now=0.0)
+    gov.reinforce("a", agent_id="bot", now=300 * _DAY)
+    gov.recompute(agent_id="bot", now=300 * _DAY)
+    rep = gov.health(agent_id="bot")
+    assert rep.total == 2
+    assert rep.active + rep.fading + rep.stale + rep.pinned == 2