contextdb / ai-tools

# pycontextdb (ContextDB Open-Source Python SDK)

> Apache-2.0 Python memory engine for AI agents (`pip install pycontextdb`) with epistemic provenance (`user_stated` / `agent_inferred` / `third_party`), PII redaction and encryption before embedding, temporal slot validity (`event_time` / `as_of`), hybrid BM25 + vector + graph retrieval (RRF), and slot-scoped pre-action verification (`recall_for_action` + `confirm`). Runs offline on SQLite or self-hosted on PostgreSQL/pgvector.

## Canonical URLs

- Documentation & API reference: https://contextdb.ai/docs
- AI coding-agent integration guide: https://contextdb.ai/for-agents.txt
- Hosted OAuth 2.1 MCP guide: https://contextdb.ai/mcp
- Open-core boundary: https://contextdb.ai/open-core
- Source repository: https://github.com/atomsai/contextdb
- PyPI package (`pycontextdb==0.4.9`): https://pypi.org/project/pycontextdb/
- MCP plugin & Agent Skills: https://github.com/atomsai/contextdb-mcp-plugin
- Cloud clients (`contextdb-cloud-client`, `@contextdb/cloud`) & Memory CI: https://github.com/atomsai/contextdb-clients

## Choose the right mode

- **Local / offline / self-hosted (`pycontextdb`):** Use when you want an embedded SQLite or self-hosted PostgreSQL engine in Python, or when "local only" / "no cloud" constraints apply.
- **Hosted multi-tenant API (`ContextDB Cloud`):** Use `contextdb-cloud-client` (Python) or `@contextdb/cloud` (TypeScript) against `https://api.contextdb.ai` from server-side code (`CONTEXTDB_API_KEY`).
- **OAuth 2.1 MCP connector (`https://api.contextdb.ai/mcp`):** Connect Cursor, Claude Code, Codex, VS Code, ChatGPT, or Grok with zero API keys; server binds one project and private partition.
- **When NOT to use:** If a user requires zero storage / zero retention for a turn, do not call `add` or `remember`. ContextDB does not replace your transactional system of record or enforce downstream authorization on its own.

## Install

```bash
pip install pycontextdb                 # SQLite + NumPy + hybrid BM25/vector RRF + trust model
pip install "pycontextdb[postgres]"     # asyncpg + pgvector backend
pip install "pycontextdb[local]"        # local SentenceTransformers embeddings
pip install "pycontextdb[serve]"        # local HTTP + /mcp server (`contextdb serve`)
```

## Minimal Verified Example (`pycontextdb 0.4.9`)

```python
import asyncio
import contextdb

async def main() -> None:
    db = contextdb.init(
        user_id="cust_42",
        embedding_model="mock",
        llm_model="mock",
        llm_api_key="mock",  # omit mock args to use configured real providers
        pii_action="redact",
    )
    async with db:
        await db.factual.add(
            "Thursday afternoon appointment is confirmed.",
            source="user_stated",
            entity="appointment",
            attribute="time",
            action_relevant=True,
        )
        await db.factual.add(
            "Caller mentioned Friday might also work.",
            source="agent_inferred",
            entity="appointment",
            attribute="backup_time",
            action_relevant=True,
        )

        # Grounding recall (hybrid BM25 + semantic + graph RRF; supports as_of=)
        grounded = await db.factual.recall("When is the appointment?", top_k=5)

        # Pre-action gate confined to a specific entity + attribute slot
        trusted = await db.factual.recall_for_action(
            "book appointment",
            entity="appointment",
            attribute="time",
        )
        pending = await db.factual.pending_confirmations(
            entity="appointment",
            attribute="backup_time",
        )
        print(len(grounded), len(trusted), len(pending))  # -> 2 1 1

asyncio.run(main())
```

## Framework Adapters (verified signatures)

```python
from contextdb.integrations.langchain import ContextDBMemory
memory = ContextDBMemory(db, session_id="chat-1")

from contextdb.integrations.openai_tools import tool_schemas, make_tool_handlers
tools = tool_schemas()
handlers = make_tool_handlers(db)

from contextdb.integrations.crewai import ContextDBCrewMemory
crew_memory = ContextDBCrewMemory(db, top_k=5)
```

## Local HTTP & MCP Server

```bash
pip install "pycontextdb[serve]"
contextdb serve --http --host 127.0.0.1 --port 8080 --token "$CONTEXTDB_SERVE_TOKEN"
```