Metadata-Version: 2.4
Name: memoptimizer
Version: 0.2.0
Summary: Your agent's memory, managed like a production system — budgeted, cached, audited.
Author: sandfairy1219
License: MIT
Project-URL: Homepage, https://github.com/sandfairy1219/memoptimizer
Keywords: llm,agent,memory,token,context-engineering,cache
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# MemOptimizer

**Your agent's memory, managed like a production system — budgeted, cached, audited.**

Existing memory layers (mem0, Zep, vector DBs) answer *"what did we remember?"*.
**MemOptimizer** answers *"what did remembering this cost, was it worth it, and how do we rank next round?"*

It treats agent memory like a **production system**: scoped token budgets, cache-stable layout, hit-rate–driven lifecycle, and auditable unit-economy receipts on every step.

---

## Why it's different

| | mem0 / Zep / vector DBs | Context compressors (rtk, headroom, LLMLingua) | Static retrieval (BM25-heavy) | **MemOptimizer** |
|---|---|---|---|---|
| Memory drafting | ✅ stores well | ❌ | ❌ | ✅ |
| Filters junk | ❌ stores everything | ❌ stateless | ⚠️ partial | ✅ auto demote by hit-rate |
| Token budget per session | ❌ dump everything | ❌ | ❌ | ✅ budget-scoped loading |
| Auto cache-stable prefix | ❌ | ❌ | ❌ | ✅ layout auto-lock |
| Auditable receipts | ❌ | ❌ | ❌ | ✅ JSON receipts |
| Adapt via self-tuning | ❌ manual | ❌ | ❌ | ✅ reflect loop |
| Portability | ❌ SDK lock-in | partial | ❌ | ✅ 100-line adapters |

**Core insight**: memory cost isn't "~remember everything" — it's *"load exactly what this session type needs, under budget, in cache-stable order, then judge hit-rate and re-rank."*

---

## Features

### 1. Budget-Scoped Memory Loading
Per session-type token budgets. Memory entries are **candidates** ranked by (domain relevance × recency × hit rate), packed under a hard token cap. Nothing extra rides along.

### 2. Auto Cache-Stable Layout
Session-persistent memory (user identity, hard rules) gets **pinned at the front + frozen** for prefix-cache hits. Anything written mid-session is **held for the next session**, never inserted mid-conversation — keeping the cached tokens cached.

### 3. Hit-Rate–Driven Lifecycle
Every memory entry logs: *was it retrieved? was it used?* Low-hit-rate entries are automatically demoted → archived → eventually dropped. High-hit-rate entries auto-promote. Memory polices itself.

### 4. Auditable Receipts
Every session emits a JSON receipt: token load per layer, per-entry hit/miss, cache efficiency, estimated USD cost, per-persona savings vs. baseline. "It actually saved money" — provable, not a vibes claim.

### 5. Drop-in Adapters
Core engine is adapter-agnostic. Get same outputs from Claude Code, Cursor, Hermes, Codex with ≤100-line adapters each.

### 6. Domain Presets
- `coding` — CLAUDE.md style, symbol-granular truncation
- `finance` — market-data cache (5-min TTL), cron diffing, no-refetch-dedupe
- `research` — web-fetch cache, char-limit presets

---

## Install

```bash
pip install memoptimizer
```

## Quick Start

```python
from memoptimizer import MemoryLayer, BudgetedContext, HitRateTracker, CacheLayout

mem = MemoryLayer("vault.json")
ctx = BudgetedContext(session_type="finance", token_budget=1500)

loaded = ctx.load(
    layer_active=mem.get_top_identity(),        # system prompt — always
    layer_procedural=mem.query("swing-trade"),  # skill-like, on demand
    layer_session_logs=mem.reload_recent(),     # weekly-fresh only
)

tracker = HitRateTracker(mem)
tracker.record_hits(loaded, used_ids=session_used_ids)   # auto-promote/demote

receipt = ctx.emit_receipt()
# → {"loaded_tokens": 1420, "dropped_tokens": 8300,
#    "cache_hit_pct": 87.2, "usd_saved": 0.043}
```

## Roadmap

- [ ] Core: `budget_builder` + `hitrate_tracker` + `cache_layout` + `receipts`
- [ ] Hermes adapter (mirror from personal deployment)
- [ ] Claude Code adapter
- [ ] Codex adapter
- [ ] Dashboard: token cost / cache-hit / USD view
- [ ] Per-preset benchmarks (vs mem0, vs no-op baseline)

## Contributing

Every design assumption documented in `docs/`. PRs welcome — especially adapter and benchmark contributions.

## License

MIT


## One-Command Setup (agent integration)

Installs the pip package, `memopt` CLI, and deploys the skill to whatever agent runtimes it finds.

Linux/macOS:
```bash
git clone https://github.com/sandfairy1219/memoptimizer
cd memoptimizer && bash install.sh
```

Windows (cmd):
```cmd
git clone https://github.com/sandfairy1219/memoptimizer
cd memoptimizer && install.bat
```

Or via pip directly (CLIE included):
```bash
pip install memoptimizer     # provides `memopt` CLI + library
memopt --help
```
