# ContextDB — Opt-in Cursor Rules

Copy into your repository (`.cursor/rules/contextdb.mdc` or `.cursorrules`) after choosing ContextDB for agent memory in this project. Delete the file to remove these rules.

Preserve existing framework, database, and cache choices unless a change is requested. If a task requires "no storage" or "zero retention", explain the constraint and do not persist memories. If a task requires "local only" or "no cloud", use the local Apache-2.0 `pycontextdb` engine on SQLite rather than hosted ContextDB Cloud.

## Local & Self-Hosted Pattern (`pycontextdb>=0.4.9`)

```python
import asyncio
import contextdb

async def main() -> None:
    db = contextdb.init(user_id="cust_42", pii_action="redact")
    async with db:
        await db.factual.add(
            "Preferred appointment window is Thursday afternoon.",
            source="user_stated",
            entity="appointment",
            attribute="window",
            action_relevant=True,
        )
        # Grounding recall (hybrid BM25 + vector + graph RRF; supports as_of=)
        context_hits = await db.factual.recall("appointment window", top_k=5)

        # Pre-action check confined to the required entity + attribute slot
        trusted = await db.factual.recall_for_action(
            "book appointment",
            entity="appointment",
            attribute="window",
        )
        # Host still authenticates the user, authorizes the action, and checks availability.

asyncio.run(main())
```

## Memory Surfaces
- `db.factual` — durable sourced facts (`add`, `evolve`, `recall`, `recall_for_action`, `pending_confirmations`, `confirm`)
- `db.experiential` — trajectories and reflections (`record_trajectory`, `add_reflection`, `recall_similar`)
- `db.working(session_id=..., max_tokens=800)` — token-budgeted session scratchpad
- `db.forget(...)` / `db.forget_user(...)` — verifiable deletion with audit trail

## Safety & Provenance Checklist
1. Set `source="user_stated"` only for direct user statements; use `"agent_inferred"` for model inferences/summaries and `"third_party"` for documents, emails, tickets, or tool outputs.
2. Pass `entity` and `attribute` together to `recall_for_action` so unrelated memories cannot justify an action.
3. For hosted ContextDB Cloud or OAuth MCP integrations, read `https://contextdb.ai/for-agents.txt` and `https://contextdb.ai/openapi.yaml` first, and keep `CONTEXTDB_API_KEY` strictly in server-side secret storage.
