Metadata-Version: 2.4
Name: foldkeep
Version: 0.9.2
Summary: Zero-dependency lossless context folding for agent sessions: pinned facts, tolerance routing, byte-for-byte expand.
Author: foldkeep contributors
License: MIT License
        
        Copyright (c) 2026 foldkeep contributors
        
        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.
Keywords: llm,agent,context-window,memory,compression
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# foldkeep

**Fold the context. Keep the facts.**

foldkeep is a zero-dependency, deterministic context-compression engine for
long agent conversations. It rolls old turns into compressed form while a
pinned fact layer keeps every decision reachable — and a lossless base lets
you expand ANY turn back byte-for-byte, even after rolling and merging.

Pure Python stdlib. No LLM calls. Millisecond latency. SQLite-backed.

## Why

Agent transcripts grow until the model drowns. Naive fixes lose the past:
tail-truncation drops early decisions; naive compression mangles numbers,
code and tool payloads. foldkeep keeps three guarantees:

1. **Pinned facts survive** — every turn pins a salient evidence line;
   a set-cover knapsack picks which lines fill the leftover budget so
   entity coverage is maximized, not clustered.
2. **Zero-tolerance content is never mangled** — code fences, JSON payloads
   and tool-call shapes are routed away from lossy compression.
3. **Nothing is ever lost** — originals persist on disk; `expand(name, seq)`
   recovers any turn byte-for-byte after rollup, consolidation or render
   drops.

## Quickstart

```python
from foldkeep import session as sess

sess.new("my-session")
for role, text in conversation:          # push turns as they happen
    sess.push("my-session", role, text)  # auto-rolls when long

out, used, dropped = sess.render("my-session", budget=800)
# -> compressed body + key-facts registry + pinned-fact block, <= 800 tok

orig = sess.expand("my-session", 3)      # byte-for-byte original of turn 3
hits = sess.search("my-session", "TKT-9001")   # recall across rolled turns
md = sess.export_md("my-session", "vault.md")  # inspectable Markdown vault
```

CLI:

```bash
python -m foldkeep selftest        # 16-case correctness battery
```

## Proven, not promised

| Suite | Result |
|---|---|
| selftest (correctness) | 16/16 |
| stress_audit (adversarial probes) | 22/22 |
| marathon (long-session checkpoints) | 9/9, push ≤ 12 ms, render ≤ 80 ms |
| agent_selftest (real build-session replay, equal budgets) | wins 5/6 cells vs tail-only & head-trunc |
| chat_selftest (this project's own chat replay) | 12/12, recall 9/9 under forced rolling |

Benchmarks live in this repo (`agent_selftest.py`, `chat_selftest.py`,
`stress_audit.py`, `long_session_test.py`) — every number reproducible.

## Design

- **Rolling compression**: newest stays verbatim, oldest compresses into a
  head; hierarchical re-merge keeps the head shrinking.
- **Three-layer render**: compressed body + one-line entity registry +
  set-cover pinned-fact block, all inside your token budget.
- **Loss-tolerance routing**: fences / JSON / tool-call shapes bypass
  lossy paths entirely.
- **Lossless base**: `orig_text` column + `originals` table + `expand()`.
- **Operator knobs**: `OC_REGISTRY_MAX` env caps registry injection.

## Status

v0.9.2. Research notes (`RESEARCH.md`) document the competitive landscape
(LLMLingua, leanctx, mnesis, FoldAgent, pi-fold, ECC, hermes-agent) and what
we learned from each.

MIT licensed. Windows/macOS/Linux, Python 3.10+.
