Metadata-Version: 2.4
Name: cluxion-Agentplugin-AutoClearMemory
Version: 0.3.1
Summary: Universal agent memory plugin (ForgetForge): recall-centric retention, tiered forgetting, Rust scoring engine for Hermes, Claude Code, and Codex.
Project-URL: Homepage, https://github.com/cluxion/cluxion-Agentplugin-AutoClearMemory
Project-URL: Repository, https://github.com/cluxion/cluxion-Agentplugin-AutoClearMemory
Project-URL: Issues, https://github.com/cluxion/cluxion-Agentplugin-AutoClearMemory/issues
Author-email: cluxion <algocean1204@users.noreply.github.com>
License-Expression: Apache-2.0
Keywords: claude-code,cluxion,codex,forgetforge,hermes-agent,memory,plugin,recall
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pyarrow>=15.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Requires-Dist: wheel>=0.45; extra == 'dev'
Description-Content-Type: text/markdown

# cluxion-Agentplugin-AutoClearMemory (ForgetForge)

범용 에이전트 **망각·기억 강화 플러그인** — **Hermes, Claude Code, Codex, Grok Build**에서 동일 core로 동작합니다.

**Repository:** https://github.com/cluxion/cluxion-Agentplugin-AutoClearMemory

## 한 줄 요약

세션 메모리가 쌓일수록 컨텍스트가 비대해집니다. ForgetForge는 **회상(Recall) 횟수**로 기억 강도를 계산하고, 오래되거나 쓰이지 않은 기억을 자동으로 낮은 tier로 내립니다. **연결된 AI**가 skill·도구 지시에 따라 recall/status/keep/forget을 호출합니다.

## 범용 에이전트 + Rust-First

| 계층 | 구현 |
|------|------|
| **Rust** (`forgetforge-engine`) | Retention scoring, tier decision |
| **Python** (`forgetforge`) | SQLite, recall tracker, pruner, CLI |
| **Agent adapter** | Hermes plugin, Claude skill, Codex CLI 가이드 |

내부 로직은 **Rust 중심**. Python·Skill은 등록·DB·JSON bridge **thin wrapper**입니다.  
Rust 바이너리가 없어도 **Python fallback**으로 동일 공식이 동작합니다.

## 이 플러그인의 역할

- **Recall이 reinforcement**: 저장 횟수가 아니라 실제 회상 \(N_r\)가 강도를 결정
- **Tiered Memory**: Hot / Warm-Episodic / Warm-Semantic / Warm-Procedural / Cold
- **Decay + Boost**: Ebbinghaus forgetting curve + spaced repetition
- **FTS5 recall**: SQLite full-text search + LIKE fallback (one transaction per recall; `score_memories` batch API for listings)
- **Brief handoff**: preprocessing/supercoder brief → episodic memory (`import-brief`)
- **Hot inject**: Hermes `pre_llm_call` hook으로 hot tier 자동 주입
- **Contradiction hints**: store 시 유사·부정 기억 경고
- **Parquet archive**: cold tier → `~/.forgetforge/archive/` (parquet + jsonl + txt)
- **Background pruner**: 6시간 주기 tier migration (`forgetforge prune`)
- **Safety**: `#keep_forever`, `#forget_this` 사용자 태그

ForgetForge는 **모델·OAuth를 소유하지 않습니다.** 연결된 AI가 도구 결과를 읽고 맥락에 반영합니다.

## 연결된 AI가 하는 일

| 상황 | 연결된 AI 동작 |
|------|----------------|
| 맥락이 커짐 | `forgetforge status` 또는 `forgetforge_status` |
| 과거 사실 필요 | `forgetforge recall <topic>` (explicit) |
| 응답에 기억 사용 | `forgetforge_recall` + `layer: implicit` |
| 세션 마무리 점검 | `forgetforge_recall` + `layer: reflection` |
| `#keep_forever` | `forgetforge keep <id>` |
| `#forget_this` | `forgetforge forget <id>` |

Hermes는 `forgetforge_*` 도구, Claude/Codex는 skill + CLI를 동일 규칙으로 따릅니다.

## Retention formula

\[
R = e^{-t / S} \times \left(1 + 0.45 \cdot N_r + 0.30 \cdot I + 0.25 \cdot F \right), \quad S = \ln(1 + N_r)
\]

## Tier 요약

| Tier | 조건 | 연결된 AI 동작 |
|------|------|----------------|
| **Hot** | 최근 7일 + \(N_r \geq 1\) | recall 결과를 맥락에 우선 반영 |
| **Warm-Episodic** | \(R \geq 0.65\) | 필요 시 recall |
| **Warm-Semantic** | \(R \geq 0.80\) | 장기 사실로 유지 |
| **Warm-Procedural** | skill + \(N_r \geq 3\) | 절차·스킬로 유지 |
| **Cold** | \(R < 0.40\) or 180일 무회상 | archive, 필요 시에만 recall |

## 빠른 시작

```bash
pip install cluxion-Agentplugin-AutoClearMemory
forgetforge init --agents=all   # DB + adapter assets + example config from wheel
forgetforge check
hermes plugins enable forgetforge   # Hermes
```

```bash
# Rust 가속 (선택)
cargo build --release --manifest-path rust/forgetforge_engine/Cargo.toml
```

## 공통 명령

| Command | Description |
|---------|-------------|
| `forgetforge store <id> --content "..."` | Store or update memory |
| `forgetforge recall <topic>` | Explicit retrieval + tier boost |
| `forgetforge keep <id>` | `#keep_forever` |
| `forgetforge forget <id>` | `#forget_this` |
| `forgetforge status` | Memory health |
| `forgetforge prune` | Pruner 1회 실행 |
| `forgetforge pruner-daemon` | Background pruner (interval from config) |
| `forgetforge import-brief --source supercoder --brief "..."` | Brief → episodic memory |
| `forgetforge hot-context` | Hot tier context block (CLI) |

## Hermes 도구 (`forgetforge` toolset)

| Tool | Description |
|------|-------------|
| `forgetforge_store` | Save or update memory (contradiction warnings when similar) |
| `forgetforge_recall` | FTS search + retrieval event (`layer`: explicit / implicit / reflection) |
| `forgetforge_status` | Tier counts, engine status |
| `forgetforge_keep` | Pin memory forever |
| `forgetforge_forget` | Mark for forgetting |
| `forgetforge_import_brief` | Import preprocessing/supercoder brief |
| `forgetforge_hot_context` | Hot tier block (also via `pre_llm_call` hook) |

## 문서

- [Docs/README.md](Docs/README.md) — **처음 읽는 분** + 목차
- [Docs/architecture.md](Docs/architecture.md)
- [Docs/design.md](Docs/design.md)
- [Docs/installation.md](Docs/installation.md)
- [Docs/agent-surfaces.md](Docs/agent-surfaces.md)
- [Docs/rust-architecture.md](Docs/rust-architecture.md)

## License

Apache-2.0