memwatch

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 32 Open GitHub ↗

Memory staleness detection and auto-expiry for LLM agents

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# memwatch

![CI](https://github.com/USERNAME/memwatch/actions/workflows/ci.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/memwatch)
![Python](https://img.shields.io/pypi/pyversions/memwatch)
![License](https://img.shields.io/badge/license-MIT-green)

**Agent memory goes stale. memwatch detects when — and expires it automatically.**

---

## The Problem

Your LLM agent knows that the user works at Google. It learned this six months ago and has been confidently using this fact in every conversation since. But three months ago, the user quietly changed jobs. The agent doesn't know this. It keeps saying "given your work at Google..." while the user has moved on.

This isn't a corner case — it's the default behavior of every agent memory system today. Facts like employer, location, phone number, and relationship status are stored once and trusted forever. There's no mechanism to ask: *is this still true?*

memwatch solves this with three complementary mechanisms. First, temporal decay: every stored fact accumulates a freshness score that decreases over time following an Ebbinghaus-inspired forgetting curve — employment facts decay faster than skill facts, which decay faster than objective facts. Second, contradiction detection: when new information arrives from the user, memwatch scans stored memories for conflicts and flags them with a confidence score. Third, category-aware TTL: each fact category has its own half-life configured from real-world change rates.

## How It Works

```
New user input arrives
        │
        ▼
┌───────────────────┐
│ Contradiction     │  Keywords + entity transitions → "no longer at Google"
│ Detector          │  Optional semantic embeddings → cosine similarity check
│ (3-level cascade) │  Value comparison → direct confirmation or conflict
└────────┬──────────┘
         │ contradictions[]
         ▼
┌───────────────────┐
│ Freshness Scorer  │  base_score = decay_factor ^ days_elapsed
│ (Ebbinghaus)      │  + access_boost = log(1 + access_count) * 0.05
│                   │  + recency_boost = 0.1 * decay_factor ^ days_since_access
└────────┬──────────┘
         │ freshness_score ∈ [0.0, 1.0]
         ▼
┌───────────────────┐
│ Category TTL      │  employment: half_life=180d, decay=0.9962/day
│ Config            │  location:   half_life=365d, decay=0.9981/day
│                   │  fact:       half_life=3650d, decay=0.9998/day
└───────────────────┘
```

## Quickstart

```bash
pip install memwatch
```

```python
from memwatch import MemWatch

mw = MemWatch()
mw.add("employer", "Google", category="employment")
mw.add("city", "Jakarta", category="location")

result = mw.check("I just moved to Surabaya for my new job at Anthropic")
print(result.summary)
# "2 contradiction(s) detected. 0 stale memories."

print(result.suggested_updates)
# [
#   {"action": "UPDATE", "memory_key": "employer", "old_value": "Google", ...},
#   {"action": "UPDATE", "memory_key": "city", "old_value": "Jakarta", ...}
# ]
```

For zero-dependency, pure-stdlib usage (no sentence-transformers needed):

```python
mw = MemWatch(use_embeddings=False)
```

## CLI Usage

```bash
# Add memories
memwatch add employer "Google" --category employment
memwatch add city "Jakarta" --category location
memwatch add role "Software Engineer" --category employment

# Check new text for contradictions
memwatch check "I moved to Surabaya and started at Anthropic"

# Inspect all memories with freshness scores
memwatch report

# Refresh all scores
memwatch refresh

# Expire a memory
memwatch forget employer

# Quick stats
memwatch stats
```

Sample `memwatch report` output:

```
════════════════════════════════════════════════════════════
  memwatch report — 2026-06-04T12:00:00
════════════════════════════════════════════════════════════
  Active:        3
  Stale:         0
  Expired:       0
  Contradicted:  0
  Avg freshness: 0.98
════════════════════════════════════════════════════════════

MEMORIES (3):
  KEY                    VALUE                SCORE LABEL    DAYS LEFT
  ────────────────────────────────────────────────────────────────────
  employer               Google                0.98 fresh          87d
  city                   Jakarta               0.98 fresh         152d
  role                   Software Engineer     0.99 fresh         87d
```

## Integrations

### mem0

```python
from memwatch.integrations.mem0_adapter import Mem0WatchedClient

client = Mem0WatchedClient(api_key="your-mem0-key", watch_db="memwatch.db")

# Add memory with staleness check
result = client.add(
    [{"role": "user", "content": "I now work at Anthropic"}],
    user_id="user_123"
)
print(result["watch_result"]["summary"])
# "1 contradiction(s) detected."
```

### LangChain

```python
from memwatch.integrations.langchain_adapter import WatchedMemory

memory = WatchedMemory(watch_db="memwatch.db")
memory.add_fact("employer", "Google", category="employment")

# Drop into any LangChain chain
memory.save_context(
    {"input": "I quit my job at Google and joined Stripe"},
    {"output": "Congratulations on the new role!"}
)
# [memwatch] 1 contradiction(s) detected. Stale: employer → Google
```

### Custom SQLite

```python
from memwatch.integrations.sqlite_adapter import SQLiteWatchAdapter

# Point at your existing agent database — no schema changes needed
adapter = SQLiteWatchAdapter(
    source_db="my_agent.db",
    watch_db="memwatch_overlay.db",
    table_name="agent_facts",
    key_column="fact_key",
    value_column="fact_value",
)
result = adapter.run_check("User mentioned moving to Bandung")
print(result["watch_result"].summary)
```

## Architecture

```
memwatch/
├── core.py          ← MemWatch (public API: add, check, get, refresh, report, forget)
├── scorer.py        ← FreshnessScorer (Ebbinghaus decay + access boost)
├── detector.py      ← ContradictionDetector (keyword → semantic → value cascade)
├── ttl_config.py    ← TTLConfig (9 categories, customizable half-lives)
├── store.py         ← MemoryStore (SQLite backend, zero ORM)
├── cli.py           ← argparse CLI
└── integrations/
    ├── mem0_adapter.py      ← mem0 proxy with staleness check
    ├── langchain_adapter.py ← LangChain Memory interface
    └── sqlite_adapter.py    ← read existing SQLite, overlay memwatch
```

## TTL Configuration

| Category     | Default Half-Life | Decay/day | Notes |
|:-------------|------------------:|----------:|:------|
| employment   | 180 days          | 0.38%     | Job title, employer |
| location     | 365 days          | 0.19%     | Home city, country |
| contact      | 730 days          | 0.10%     | Phone, email |
| preference   | 365 days          | 0.19%     | Food, hobbies |
| relationship | 730 days          | 0.10%     | Marital status |
| skill        | 1095 days         | 0.06%     | Technical skills |
| belief       | 365 days          | 0.19%     | Opinions, values |
| fact         | 3650 days         | 0.02%     | Objective facts |
| general      | 365 days          | 0.19%     | Default/uncategorized |

Customize per deployment:

```python
from memwatch import MemWatch, TTLConfig

config = TTLConfig()
config.set_half_life("employment", 90)   # faster decay for your use case
config.set_half_life("location", 730)    # slower decay

mw = MemWatch(ttl_config=config)
```

## Freshness Score

The scoring formula combines three signals:

```
base_score    = decay_factor ^ days_since_created        # Ebbinghaus exponential
access_boost  = log(1 + access_count) * 0.05             # Spaced repetition effect
recency_boost = 0.1 * decay_factor ^ days_since_last_access

final_score = min(1.0, base_score + access_boost + recency_boost)
```

Labels: `fresh` (≥0.8), `aging` (≥0.5), `stale` (≥0.3), `expired` (<0.3)

## Benchmarks

Coming soon — planned: throughput (memories/sec) for check() with and without embeddings, SQLite query latency at 10k / 100k stored memories.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). In short: fork, make a branch, write tests, open a PR. All tests must pass (`pytest tests/ -v`).

## Academic References

- Ebbinghaus, H. (1885). *Über das Gedächtnis* — forgetting curve foundation
- Zhong et al. (2023). *MemoryBank: Enhancing Large Language Models with Long-Term Memory* — decay scoring adaptation
- Park et al. (2023). *Generative Agents: Interactive Simulacra of Human Behavior* (Stanford) — memory importance and retrieval

## License

MIT — see [LICENSE](LICENSE).

memwatch

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README