cluxion-Agentplugin-AutoClearMemory 0.2.0__py3-none-any.whl

cluxion_agentplugin_autoclearmemory-0.2.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: cluxion-Agentplugin-AutoClearMemory
+Version: 0.2.0
+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'
+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
+- **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
+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

cluxion_agentplugin_autoclearmemory-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+forgetforge/__init__.py,sha256=Wkwg9PUkaGjHLMEaYqFYYRLoVSlb80kQ1nRzGUSsuSg,134
+forgetforge/archive.py,sha256=Qt4pM1mGPAzy0RVd90P_SmuSviCWhlWP5A5wKSnJOxk,1482
+forgetforge/cli.py,sha256=R8kU8zUbbK5DqPPAycjTqgLVrMdiB81kkX4hnIsJ68k,7898
+forgetforge/config.py,sha256=1FRtN9xdLaA989tNmBvfoATzb2nsrEKmraavxJaQHpk,1571
+forgetforge/contradiction.py,sha256=f0S0C3zBQIPyPK2FJkleujKsXt_BXsPXUe4NK2t3WyA,2187
+forgetforge/db.py,sha256=U4Cf1Tj3pAj9ofqg0yM-40279iP06T-8MdOEcpWQsiQ,9574
+forgetforge/hot_inject.py,sha256=rH_tUL9LCaBWYiap2Vi8_fA-dFpAFTpqQR3XFN9vmQA,843
+forgetforge/import_brief.py,sha256=QAp-usJ1Ih2HWfSrGDjaw2gfpa4_VRFeOrSk_SWAj_E,1318
+forgetforge/pruner.py,sha256=aUW48-inawfOG8ljNRrfI_GrNlyRq5A-_CB1s3Kl-x4,2589
+forgetforge/recall.py,sha256=5_DLGNMBmvwNFPqGdjZI1cl3T0H-2gpXY_O5E4PPfnY,3754
+forgetforge/rust_bridge.py,sha256=rnsYMk95bXynzXjNr-_Ar8PYEgWd37WlwgnaR4lzRbA,4161
+forgetforge/schemas.py,sha256=d23VRrG3iqPaog3igcdkaugulZHKqU0CmyyXIB6C4jc,2236
+forgetforge/store.py,sha256=pTApLBXk-zN2gLccUqWb-Qfms6MURFgqOLvxQaop9uo,2687
+forgetforge/adapters/__init__.py,sha256=OcCz6Ib0sIILnkPL4xqNEU0TldjdQIi1NOxiGx6UeuU,70
+forgetforge/adapters/hermes.py,sha256=5W_sqEy3uGdoT5i2FZayGFqfwGXtlvBuljhAMISCa4A,5170
+cluxion_agentplugin_autoclearmemory-0.2.0.dist-info/METADATA,sha256=xMpKzjiwZRScCvzDbcHao-DBwFb3xAgLFK5NFAmhONM,6401
+cluxion_agentplugin_autoclearmemory-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cluxion_agentplugin_autoclearmemory-0.2.0.dist-info/entry_points.txt,sha256=144bKiDTBBCqpsiev-IoSdW5xmdZPLgWbvgT8K9NW30,128
+cluxion_agentplugin_autoclearmemory-0.2.0.dist-info/RECORD,,

cluxion_agentplugin_autoclearmemory-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cluxion_agentplugin_autoclearmemory-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+forgetforge = forgetforge.cli:main
+
+[hermes_agent.plugins]
+forgetforge = forgetforge.adapters.hermes:register

forgetforge/__init__.py

@@ -0,0 +1,5 @@
+"""ForgetForge — recall-centric memory plugin for universal agent environments."""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

forgetforge/adapters/__init__.py

@@ -0,0 +1,3 @@
+"""Agent surface adapters for ForgetForge."""
+
+__all__: list[str] = []

forgetforge/adapters/hermes.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+
+from forgetforge import db, hot_inject, import_brief
+from forgetforge.config import load_config
+from forgetforge.schemas import (
+    FORGET_SCHEMA,
+    HOT_CONTEXT_SCHEMA,
+    IMPORT_BRIEF_SCHEMA,
+    KEEP_SCHEMA,
+    RECALL_SCHEMA,
+    STATUS_SCHEMA,
+    STORE_SCHEMA,
+)
+from forgetforge import store as store_api
+
+
+def register(ctx: object) -> None:
+    ctx.register_tool(
+        name="forgetforge_store",
+        toolset="forgetforge",
+        schema=STORE_SCHEMA,
+        handler=_wrap(_handle_store),
+        emoji="💾",
+    )
+    ctx.register_tool(
+        name="forgetforge_recall",
+        toolset="forgetforge",
+        schema=RECALL_SCHEMA,
+        handler=_wrap(_handle_recall),
+        emoji="🧠",
+    )
+    ctx.register_tool(
+        name="forgetforge_status",
+        toolset="forgetforge",
+        schema=STATUS_SCHEMA,
+        handler=_wrap(_handle_status),
+        emoji="📊",
+    )
+    ctx.register_tool(
+        name="forgetforge_keep",
+        toolset="forgetforge",
+        schema=KEEP_SCHEMA,
+        handler=_wrap(_handle_keep),
+        emoji="📌",
+    )
+    ctx.register_tool(
+        name="forgetforge_forget",
+        toolset="forgetforge",
+        schema=FORGET_SCHEMA,
+        handler=_wrap(_handle_forget),
+        emoji="🗑️",
+    )
+    ctx.register_tool(
+        name="forgetforge_import_brief",
+        toolset="forgetforge",
+        schema=IMPORT_BRIEF_SCHEMA,
+        handler=_wrap(_handle_import_brief),
+        emoji="📥",
+    )
+    ctx.register_tool(
+        name="forgetforge_hot_context",
+        toolset="forgetforge",
+        schema=HOT_CONTEXT_SCHEMA,
+        handler=_wrap(_handle_hot_context),
+        emoji="🔥",
+    )
+    register_hook = getattr(ctx, "register_hook", None)
+    if callable(register_hook):
+        register_hook("pre_llm_call", _pre_llm_hot_inject)
+
+
+def _pre_llm_hot_inject(**_: object) -> dict[str, str]:
+    return hot_inject.hot_context_payload()
+
+
+def _wrap(callback: Callable[[dict[str, object]], dict[str, object]]) -> Callable[[dict[str, object]], str]:
+    def handler(args: dict[str, object], **_: object) -> str:
+        try:
+            return json.dumps(callback(args), ensure_ascii=False, sort_keys=True)
+        except (ValueError, OSError) as exc:
+            return json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False, sort_keys=True)
+
+    return handler
+
+
+def _conn():
+    cfg = load_config()
+    return db.connect(cfg.db_path)
+
+
+def _handle_store(args: dict[str, object]) -> dict[str, object]:
+    conn = _conn()
+    try:
+        stored = store_api.store_memory(
+            conn,
+            memory_id=str(args.get("memory_id", "")),
+            content=str(args.get("content", "")),
+            importance=float(args.get("importance", 0.5)),
+            frequency=float(args.get("frequency", 0.0)),
+            is_procedural=bool(args.get("is_procedural", False)),
+        )
+        return {"ok": True, "stored": stored}
+    finally:
+        conn.close()
+
+
+def _handle_recall(args: dict[str, object]) -> dict[str, object]:
+    query = str(args.get("query", "")).strip()
+    layer = str(args.get("layer", "explicit"))
+    if not query:
+        raise ValueError("query is required")
+    conn = _conn()
+    try:
+        return store_api.recall_with_feedback(conn, query, layer=layer)
+    finally:
+        conn.close()
+
+
+def _handle_status(_: dict[str, object]) -> dict[str, object]:
+    from forgetforge import rust_bridge
+
+    conn = _conn()
+    try:
+        return {"ok": True, "stats": db.memory_stats(conn), "rust_engine": rust_bridge.engine_available()}
+    finally:
+        conn.close()
+
+
+def _handle_keep(args: dict[str, object]) -> dict[str, object]:
+    memory_id = str(args.get("memory_id", "")).strip()
+    if not memory_id:
+        raise ValueError("memory_id is required")
+    conn = _conn()
+    try:
+        ok = db.mark_keep_forever(conn, memory_id)
+        return {"ok": ok, "memory_id": memory_id}
+    finally:
+        conn.close()
+
+
+def _handle_forget(args: dict[str, object]) -> dict[str, object]:
+    memory_id = str(args.get("memory_id", "")).strip()
+    if not memory_id:
+        raise ValueError("memory_id is required")
+    conn = _conn()
+    try:
+        ok = db.mark_forget(conn, memory_id)
+        return {"ok": ok, "memory_id": memory_id}
+    finally:
+        conn.close()
+
+
+def _handle_import_brief(args: dict[str, object]) -> dict[str, object]:
+    conn = _conn()
+    try:
+        return import_brief.import_brief(
+            conn,
+            source=str(args.get("source", "manual")),
+            brief=str(args.get("brief", "")),
+            memory_id=str(args.get("memory_id", "")).strip() or None,
+            importance=float(args.get("importance", 0.65)),
+        )
+    finally:
+        conn.close()
+
+
+def _handle_hot_context(args: dict[str, object]) -> dict[str, object]:
+    limit = int(args.get("limit", 8))
+    conn = _conn()
+    try:
+        context = hot_inject.build_hot_context(conn, limit=limit)
+        return {"ok": True, "context": context, "has_hot": bool(context)}
+    finally:
+        conn.close()
+
+
+__all__ = ["register"]

forgetforge/archive.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from forgetforge.config import ForgetForgeConfig
+
+
+def write_cold_archive(
+    cfg: ForgetForgeConfig,
+    *,
+    memory_id: str,
+    content: str,
+    retention: float,
+    tier: str,
+) -> dict[str, Any]:
+    cfg.archive_dir.mkdir(parents=True, exist_ok=True)
+    summary = content.strip().splitlines()[0][:500] if content.strip() else ""
+    record = {
+        "memory_id": memory_id,
+        "retention": retention,
+        "tier": tier,
+        "summary": summary,
+        "archived_at": datetime.now(UTC).replace(microsecond=0).isoformat(),
+    }
+    parquet_path = cfg.archive_dir / f"{memory_id}.parquet"
+    jsonl_path = cfg.archive_dir / "cold_archive.jsonl"
+    written = "jsonl"
+    try:
+        import pyarrow as pa
+        import pyarrow.parquet as pq
+
+        table = pa.Table.from_pylist([record])
+        pq.write_table(table, parquet_path)
+        written = "parquet"
+    except ImportError:
+        parquet_path = None
+    with jsonl_path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+    txt_path = cfg.archive_dir / f"{memory_id}.txt"
+    txt_path.write_text(f"# retention={retention:.3f}\n{summary}\n", encoding="utf-8")
+    return {"format": written, "parquet": str(parquet_path) if parquet_path else None, "jsonl": str(jsonl_path)}
+
+
+__all__ = ["write_cold_archive"]

forgetforge/cli.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from forgetforge import __version__, db, hot_inject, import_brief, pruner, rust_bridge, store
+from forgetforge.config import default_home, load_config
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.command == "check":
+        return _check()
+    if args.command == "init":
+        return _init(args)
+    if args.command == "status":
+        return _status()
+    if args.command == "recall":
+        return _recall(args)
+    if args.command == "keep":
+        return _keep(args)
+    if args.command == "forget":
+        return _forget(args)
+    if args.command == "prune":
+        return _prune()
+    if args.command == "store":
+        return _store(args)
+    if args.command == "pruner-daemon":
+        return _pruner_daemon(args)
+    if args.command == "import-brief":
+        return _import_brief(args)
+    if args.command == "hot-context":
+        return _hot_context(args)
+    parser.print_help(sys.stderr)
+    return 2
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="forgetforge")
+    parser.add_argument("--version", action="version", version=f"forgetforge {__version__}")
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("check", help="Check Rust engine and database paths")
+    init = sub.add_parser("init", help="Initialize ~/.forgetforge and optional agent adapters")
+    init.add_argument("--agents", default="all", help="Comma-separated: hermes,claude,codex or all")
+    sub.add_parser("status", help="Memory health summary")
+    recall_cmd = sub.add_parser("recall", help="Recall memories matching a query")
+    recall_cmd.add_argument("query")
+    keep = sub.add_parser("keep", help="Mark memory as keep_forever")
+    keep.add_argument("memory_id")
+    forget = sub.add_parser("forget", help="Mark memory for forgetting")
+    forget.add_argument("memory_id")
+    sub.add_parser("prune", help="Run background pruner once")
+    store_cmd = sub.add_parser("store", help="Store or update a memory")
+    store_cmd.add_argument("memory_id")
+    store_cmd.add_argument("--content", required=True)
+    store_cmd.add_argument("--importance", type=float, default=0.5)
+    store_cmd.add_argument("--frequency", type=float, default=0.0)
+    store_cmd.add_argument("--procedural", action="store_true")
+    daemon = sub.add_parser("pruner-daemon", help="Run pruner on interval (background)")
+    daemon.add_argument("--interval-hours", type=int, default=None)
+    daemon.add_argument("--once", action="store_true", help="Run one cycle then exit")
+    brief = sub.add_parser("import-brief", help="Import preprocessing/supercoder brief into memory")
+    brief.add_argument("--source", choices=["preprocessing", "supercoder", "manual"], required=True)
+    brief.add_argument("--brief", required=True)
+    brief.add_argument("--memory-id", default=None)
+    brief.add_argument("--importance", type=float, default=0.65)
+    hot = sub.add_parser("hot-context", help="Print hot-tier context block")
+    hot.add_argument("--limit", type=int, default=8)
+    return parser
+
+
+def _check() -> int:
+    home = default_home()
+    payload = {
+        "ok": True,
+        "home": str(home),
+        "rust_engine": rust_bridge.engine_available(),
+        "db_exists": (home / "db.sqlite").exists(),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _init(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    cfg.home.mkdir(parents=True, exist_ok=True)
+    cfg.archive_dir.mkdir(parents=True, exist_ok=True)
+    conn = db.connect(cfg.db_path)
+    conn.close()
+    agents = _parse_agents(str(args.agents))
+    adapter_root = Path(__file__).resolve().parents[2] / "adapters"
+    installed = []
+    for agent in agents:
+        src = adapter_root / agent
+        if src.exists():
+            installed.append(agent)
+    example = Path(__file__).resolve().parents[2] / "config.yaml.example"
+    target = cfg.home / "config.yaml"
+    if example.exists() and not target.exists():
+        shutil.copy(example, target)
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "home": str(cfg.home),
+                "db": str(cfg.db_path),
+                "agents": installed,
+                "config": str(target),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+def _status() -> int:
+    from forgetforge import recall
+
+    cfg = load_config()
+    conn = db.connect(cfg.db_path)
+    stats = db.memory_stats(conn)
+    hot = [recall.score_memory(row) for row in db.list_memories(conn, limit=50) if row.tier == "hot"]
+    conn.close()
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "rust_engine": rust_bridge.engine_available(),
+                "stats": stats,
+                "hot_samples": hot[:5],
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+def _recall(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    conn = db.connect(cfg.db_path)
+    payload = store.recall_with_feedback(conn, str(args.query))
+    conn.close()
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _store(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    conn = db.connect(cfg.db_path)
+    stored = store.store_memory(
+        conn,
+        memory_id=str(args.memory_id),
+        content=str(args.content),
+        importance=float(args.importance),
+        frequency=float(args.frequency),
+        is_procedural=bool(args.procedural),
+    )
+    conn.close()
+    print(json.dumps({"ok": True, "stored": stored}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _pruner_daemon(args: argparse.Namespace) -> int:
+    pruner.run_pruner_daemon(interval_hours=args.interval_hours, run_once=bool(args.once))
+    return 0
+
+
+def _import_brief(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    conn = db.connect(cfg.db_path)
+    result = import_brief.import_brief(
+        conn,
+        source=str(args.source),
+        brief=str(args.brief),
+        memory_id=str(args.memory_id) if args.memory_id else None,
+        importance=float(args.importance),
+    )
+    conn.close()
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _hot_context(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    conn = db.connect(cfg.db_path)
+    context = hot_inject.build_hot_context(conn, limit=int(args.limit))
+    conn.close()
+    print(json.dumps({"ok": True, "context": context, "has_hot": bool(context)}, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _keep(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    conn = db.connect(cfg.db_path)
+    ok = db.mark_keep_forever(conn, str(args.memory_id))
+    conn.close()
+    print(json.dumps({"ok": ok, "memory_id": args.memory_id}, ensure_ascii=False))
+    return 0 if ok else 1
+
+
+def _forget(args: argparse.Namespace) -> int:
+    cfg = load_config()
+    conn = db.connect(cfg.db_path)
+    ok = db.mark_forget(conn, str(args.memory_id))
+    conn.close()
+    print(json.dumps({"ok": ok, "memory_id": args.memory_id}, ensure_ascii=False))
+    return 0 if ok else 1
+
+
+def _prune() -> int:
+    cfg = load_config()
+    conn = db.connect(cfg.db_path)
+    result = pruner.run_pruner(conn, config=cfg)
+    conn.close()
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _parse_agents(raw: str) -> list[str]:
+    if raw.strip().lower() == "all":
+        return ["hermes", "claude", "codex"]
+    return [part.strip().lower() for part in raw.split(",") if part.strip()]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())