pip install agent-recall-ai
agent-recall-ai install-hooks

pip install agent-recall-ai
agent-recall-ai install-hooks          # adds a Stop hook to .claude/settings.json

agent-recall-ai resume <session-name>

pip install agent-recall-ai

from agent_recall_ai import Checkpoint

with Checkpoint("refactor-auth") as cp:
    cp.set_goal("Replace python-jose with PyJWT")
    cp.add_constraint("Do not break the public API")
    cp.record_decision(
        "Use PyJWT",
        reasoning="Actively maintained; python-jose has unpatched CVEs",
        alternatives_rejected=["python-jose", "authlib"],
    )
    cp.record_file_modified("auth/tokens.py")
    cp.record_tokens(prompt=18000, completion=2000)
    # State auto-saves to .agent-recall-ai/

from agent_recall_ai import resume

state = resume("refactor-auth")
print(state.resume_prompt())

## Resuming Agent Session
**Session:** refactor-auth  |  **Checkpoint:** #3
**Started:** 2025-04-28 14:22 UTC

### Goals
- Replace python-jose with PyJWT

### Active Constraints
- Do not break the public API

### Decisions Made
- **Use PyJWT**
  Reason: Actively maintained; python-jose has unpatched CVEs
  Rejected: python-jose, authlib

### Files Modified
- `auth/tokens.py`

**Token usage so far:** 20,000 tokens  |  **Cost:** $0.0014

# Async context manager — works with every modern agent framework
async with Checkpoint("my-async-agent") as cp:
    cp.set_goal("Analyze sales data")
    result = await openai_client.chat.completions.create(...)
    cp.record_tokens(prompt=result.usage.prompt_tokens,
                     completion=result.usage.completion_tokens)
# Non-blocking save via asyncio.to_thread on exit

# One-line decorator — sync or async, both work
@checkpoint("refactor-auth")
async def run_agent(goal: str, cp=None):
    cp.set_goal(goal)
    cp.add_constraint("Do not break the public API")
    result = await do_work()
    cp.record_decision("Chose streaming", reasoning="Lower latency")
    return result

# cp is injected automatically when declared as a parameter
await run_agent("Replace python-jose with PyJWT")

cp.record_decision(
    "Use JWT in httpOnly cookie",
    reasoning="CSRF risk is lower than XSS at our scale",
    alternatives_rejected=["localStorage", "sessionStorage"],
    tags=["security", "auth"],
)

from agent_recall_ai import Checkpoint, CostMonitor, TokenMonitor, DriftMonitor

with Checkpoint(
    "long-refactor",
    monitors=[
        CostMonitor(budget_usd=5.00),               # raises CostBudgetExceeded at $5
        TokenMonitor(warn_at=0.70, compress_at=0.88),  # alerts at 70%/88% fill
        DriftMonitor(),                              # detects constraint violations
    ],
) as cp:
    ...

from agent_recall_ai.privacy import PIIRedactor, SensitivityLevel

redactor = PIIRedactor(sensitivity=SensitivityLevel.HIGH)
# Scans for: API keys, passwords, emails, SSNs, credit cards, private IPs

with Checkpoint("prod-deploy", redactor=redactor) as cp:
    cp.record_decision(
        "Rotate DB credentials",
        reasoning="Old password was SuperSecret123 — now rotated",
    )
    # Saved to disk: reasoning="... [REDACTED:password] — now rotated"
    # In memory (live agent): original value retained

from agent_recall_ai.privacy.presidio_backend import PresidioBackend
from agent_recall_ai.privacy import PIIRedactor

backend = PresidioBackend(entities=["PERSON", "LOCATION", "EMAIL_ADDRESS", "PHONE_NUMBER"])
redactor = PIIRedactor(sensitivity=SensitivityLevel.HIGH, extra_backend=backend)
# Now catches: "Contact John Smith at his office in New York"

from agent_recall_ai.privacy import VersionedSchema

with Checkpoint("future-proof", schema=VersionedSchema()) as cp:
    ...
# Every checkpoint carries schema_version="1.0.0"
# BFS migration graph handles forward AND backward compatibility
# A checkpoint saved today loads cleanly 6 months from now

from agent_recall_ai.core.semantic_pruner import SemanticPruner

pruner = SemanticPruner()
compressed, stats = pruner.compress_context(messages, target_tokens=4096)
print(stats)
# {"original_tokens": 22000, "compressed_tokens": 4096,
#  "anchors_protected": 7, "compression_ratio": 0.81}

# OpenAI SDK — with ConversationRepair for orphaned tool_call IDs
from agent_recall_ai.adapters import OpenAIAdapter
adapter = OpenAIAdapter(cp, repair_conversations=True)
client = adapter.wrap(openai.OpenAI())
# If the session was interrupted mid-tool-call, the history is auto-repaired

# Anthropic SDK — automatic prompt caching (90% cost reduction)
from agent_recall_ai.adapters import AnthropicAdapter
adapter = AnthropicAdapter(cp)   # enable_prompt_caching=True by default
# Injects cache_control breakpoints on system, tools, and last user message
# Pre-counts tokens before each call → state.metadata["pre_inference_tokens"]
client = adapter.wrap(anthropic.Anthropic())

# LangChain
from agent_recall_ai.adapters import LangChainAdapter
handler = LangChainAdapter(cp).as_callback()

# CrewAI — records each task completion as a Decision Anchor
from agent_recall_ai.adapters import CrewAIAdapter
crew = CrewAIAdapter(cp).wrap(Crew(agents=[...], tasks=[...]))
result = crew.kickoff()  # every task boundary auto-checkpointed

# smolagents (HuggingFace) — records every reasoning step
from agent_recall_ai.adapters import smolagentsAdapter
agent = smolagentsAdapter(cp).wrap(CodeAgent(tools=[...], model=model))
result = agent.run("Analyze the sales data in data.csv")

from langgraph.graph import StateGraph
from agent_recall_ai.adapters import LangGraphAdapter

# Before: MemorySaver() or SqliteSaver()
# After:
checkpointer = LangGraphAdapter.from_sqlite("checkpoints.db")

graph = builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "my-session"}}

# Every .invoke() is now auto-checkpointed with full reasoning state
result = graph.invoke({"messages": [...]}, config)

# After session death — resumes from exact checkpoint
result = graph.invoke(None, config)

# Fork the main session to explore an alternative reasoning path
checkpointer.fork("main-session", "alt-branch-1")

alt_config = {"configurable": {"thread_id": "alt-branch-1"}}
alt_result = graph.invoke({"messages": [...]}, alt_config)
# main-session is unchanged; alt-branch-1 diverges from the same checkpoint

with Checkpoint("main-task") as cp:
    cp.set_goal("Refactor auth module")
    cp.record_decision("Use PyJWT", reasoning="Better maintained")

    # Explore a different approach
    alt = cp.fork("main-task-alt")
    alt.record_decision("Try python-jose instead", reasoning="Lighter weight")
    alt.save()
    # parent unchanged, alt has all parent state plus new decision

from agent_recall_ai.exporters import OTLPExporter

# Jaeger (local dev)
exporter = OTLPExporter(endpoint="http://localhost:4317", insecure=True)

# Datadog APM
from agent_recall_ai.exporters import DatadogExporter
exporter = DatadogExporter(env="production", service="my-agent")

with Checkpoint("prod-task") as cp:
    exporter.attach(cp)   # auto-exports a trace on every save
    ...

# Or export after-the-fact
exporter.export_session(cp.state)

checkpoint:{seq}
├── decision:{id}       attributes: summary, reasoning, alternatives_rejected, tags
├── tool:{name}         attributes: input_summary, output_tokens, compressed
└── alert:{type}        attributes: severity, message

from agent_recall_ai.persistence.redis_provider import RedisProvider

store = RedisProvider(url="redis://redis.internal:6379", prefix="myapp")
with Checkpoint("prod-task", store=store) as cp:
    ...
# TTL: 7 days (active), 1 day (completed)
# Publishes events to myapp:events on each save
# Sorted index for fast session listing

# Agent 1 completes its subtask
payload = cp.as_handoff()
# {"session_id": "...", "decisions": [...], "constraints": [...],
#  "files_modified": [...], "next_steps": [...], "cost_usd": 0.14}

# Agent 2 picks up exactly where Agent 1 left off
with Checkpoint("agent-2", store=store) as cp2:
    cp2.set_context(f"Continuing from agent-1 (${payload['cost_usd']:.2f} spent)")
    for d in payload["decisions"]:
        cp2.record_decision(d["summary"], reasoning=d["reasoning"])

# Session management
agent-recall-ai list                            # all sessions (color-coded by status)
agent-recall-ai list --status active            # filter by status
agent-recall-ai inspect refactor-auth           # full details with decisions, files, alerts
agent-recall-ai inspect refactor-auth --full    # every decision and tool call
agent-recall-ai resume  refactor-auth           # print resume prompt — paste into new session
agent-recall-ai export  refactor-auth --format json > state.json
agent-recall-ai export  refactor-auth --format handoff > handoff.json
agent-recall-ai export  refactor-auth --format agenttest > test_auth.py
agent-recall-ai delete  refactor-auth
agent-recall-ai status                          # total cost, token spend, session counts

# One-time setup (zero-code protection)
agent-recall-ai install-hooks                   # Claude Code
agent-recall-ai install-hooks --tool cursor     # Cursor
agent-recall-ai install-hooks --tool windsurf   # Windsurf
agent-recall-ai install-hooks --global          # install globally (all projects)
agent-recall-ai install-hooks --dry-run         # preview changes without writing

agent_recall_ai/
├── checkpoint.py            Primary API — Checkpoint context manager
├── core/
│   ├── state.py             TaskState (Pydantic v2), Decision, FileChange, Alert
│   ├── tracker.py           Token cost table (GPT-4o, Claude 3.5 Sonnet, etc.)
│   ├── compressor.py        Tool output + decision log compression
│   └── semantic_pruner.py   SemanticPruner with Decision Anchor protection
├── storage/
│   ├── disk.py              DiskStore — zero-config SQLite (default)
│   └── memory.py            MemoryStore — for tests
├── persistence/
│   ├── sqlite_provider.py   Full SQLite with decision_log full-text search
│   └── redis_provider.py    Redis with TTL, pub/sub, sorted index
├── monitors/                CostMonitor, TokenMonitor, DriftMonitor, ...
├── adapters/
│   ├── anthropic_adapter.py Prompt caching + pre-inference token count
│   ├── openai_adapter.py    ConversationRepair for orphaned tool_call IDs
│   ├── langgraph_adapter.py BaseCheckpointSaver drop-in + thread forking
│   ├── langchain_adapter.py CallbackHandler + MessageHistory
│   ├── crewai_adapter.py    kickoff() + task boundary instrumentation
│   └── smolagents_adapter.py run() + step() + log harvesting
├── exporters/
│   ├── otlp.py              OpenTelemetry spans → Datadog / Jaeger / Grafana
│   └── datadog.py           Datadog APM convenience wrapper
├── privacy/
│   ├── redactor.py          PIIRedactor — 14 categories, runs pre-serialization
│   ├── versioned_schema.py  VersionedSchema — BFS migration graph
│   └── presidio_backend.py  Optional NER-based PII via Microsoft Presidio
└── cli/main.py              Typer CLI (list, inspect, resume, export, delete, install-hooks)

pip install agent-recall-ai              # minimal
pip install agent-recall-ai[redis]       # + Redis support
pip install agent-recall-ai[langchain]   # + LangChain integration
pip install agent-recall-ai[langgraph]   # + LangGraph BaseCheckpointSaver
pip install agent-recall-ai[crewai]      # + CrewAI integration
pip install agent-recall-ai[smolagents]  # + smolagents integration
pip install agent-recall-ai[semantic]    # + embedding-based compression
pip install agent-recall-ai[otlp-grpc]  # + OpenTelemetry gRPC export
pip install agent-recall-ai[otlp-http]  # + OpenTelemetry HTTP export
pip install agent-recall-ai[presidio]   # + NER-based PII (Microsoft Presidio)
pip install agent-recall-ai[all]        # everything

# Development
pip install -e ".[dev]"
pytest tests/ -v    # 289 passing, 17 skipped (optional deps)

[![Protected by agent-recall-ai](https://img.shields.io/badge/agent--recall-protected-00c896)](https://github.com/srinathsankara/agent-recall-ai)