pycontextdb 0.4.7__tar.gz → 0.4.9__tar.gz

pycontextdb-0.4.9/.github/copilot-instructions.md

@@ -0,0 +1,49 @@
+# GitHub Copilot Instructions — ContextDB
+
+Opt-in project instructions for repositories that have chosen **ContextDB** (`pip install pycontextdb`, Apache-2.0, or hosted ContextDB Cloud at `https://contextdb.ai/for-agents.txt`). Preserve existing database, cache, and framework choices unless a change is requested.
+
+## Choose the matching deployment mode
+- **Local / offline / self-hosted (`pycontextdb`):** SQLite default or PostgreSQL (`storage_url="postgresql://..."`). Use this whenever "local only" or "no cloud" applies.
+- **Hosted Cloud API or OAuth MCP:** see `https://contextdb.ai/for-agents.txt` and `https://contextdb.ai/openapi.yaml`. Keep `CONTEXTDB_API_KEY` in server-side secrets only.
+- **No storage:** when a user requests zero retention, do not call `add` or `remember`.
+
+## Core `pycontextdb` pattern (`0.4.9+`)
+
+```python
+import asyncio
+import contextdb
+
+async def main() -> None:
+    db = contextdb.init(user_id="user_123", pii_action="redact")
+    async with db:
+        await db.factual.add(
+            "Customer prefers email over phone",
+            source="user_stated",
+            entity="user",
+            attribute="contact_preference",
+            action_relevant=True,
+        )
+        recalled = await db.factual.recall("preferred contact channel?", top_k=5)
+        trusted = await db.factual.recall_for_action(
+            "send account update",
+            entity="user",
+            attribute="contact_preference",
+        )
+
+asyncio.run(main())
+```
+
+## Framework adapters (optional)
+
+```python
+from contextdb.integrations.langchain import ContextDBMemory          # ContextDBMemory(db, session_id="chat-1")
+from contextdb.integrations.openai_tools import tool_schemas, make_tool_handlers
+from contextdb.integrations.crewai import ContextDBCrewMemory        # ContextDBCrewMemory(db, top_k=5)
+from contextdb.integrations.autogen import ContextDBAutoGenMemory    # ContextDBAutoGenMemory(db)
+```
+
+## Guidelines
+- Use `async with db:` and `await` on all SDK calls.
+- Label provenance honestly (`user_stated`, `agent_inferred`, `third_party`).
+- Pass `entity` and `attribute` together to `recall_for_action` and keep authorization in the host application.
+- Canonical docs: https://contextdb.ai/docs · GitHub: https://github.com/atomsai/contextdb

{pycontextdb-0.4.7 → pycontextdb-0.4.9}/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 ## Unreleased
 
+## 0.4.9 — 2026-11-15
+
+- `ContextDB.pending_confirmations()` (unslotted) now excludes superseded
+  (`superseded_by is not None`) and expired (`not is_valid_at(moment)`)
+  revisions, matching slotted `pending_confirmations(entity=..., attribute=...)`
+  so callers no longer receive historical revisions that have already been
+  replaced.
+- `contextdb.mcp` local MCP server adds `event_time` to `remember`, `as_of` to
+  `recall`, optional `entity` and `attribute` slot scoping to
+  `recall_for_action` and `pending_confirmations`, and explicit parameter
+  descriptions across all six MCP tools.
+- `PostgresStore.search_text()` serves warm lexical identifier lookups from the
+  in-process index cache when synchronized with the store revision.
+- `pyproject.toml` updates `Documentation` to `https://contextdb.ai/docs`, adds
+  `For AI Agents`, `MCP Connector`, and `Changelog` project URLs, and expands
+  PyPI discovery keywords (`mcp`, `model-context-protocol`, `provenance`,
+  `pii-redaction`, `sqlite`, `postgresql`, `pgvector`, `bm25`,
+  `temporal-memory`).
+- `ai-tools/` (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `llms.txt`,
+  `llms-full.txt`, `.github/copilot-instructions.md`) ships verified `0.4.9`
+  API signatures and opt-in, owner-controlled project rules.
+
+## 0.4.8 — 2026-10-21
+
+- `factual.add()`, `add_fast()`, and `add_many()` accept optional `event_time`
+  and set `valid_from = event_time` (closing superseded slot occupants at
+  `valid_until = event_time`) so backdated writes carry their real validity
+  window.
+- `RetrievalEngine.search_scored()` applies `as_of` filtering in `SQLiteStore`
+  and `PostgresStore` before top-k truncation and computes salience decay
+  relative to `as_of`.
+- `RetrievalEngine.search_scored()` adds a general BM25 keyword ranking arm
+  (`_bm25_ranking`) fused via Reciprocal Rank Fusion alongside semantic and
+  graph rankings, while keeping `recall_for_action` relevance-floor bypass
+  restricted to digit-bearing `identifier_tokens`.
+- `render_recalled_context()` adds optional `include_timestamps` and
+  `chronological` ordering and marks `CONTESTED` memories.
+
 ## 0.4.7 — 2026-10-12
 
 - `forget_user` now removes what the user added to shared entities. Entity

pycontextdb-0.4.9/COMMERCIAL.md

@@ -0,0 +1,71 @@
+# Commercial use and trademark
+
+The software in this repository is open source under the Apache License,
+Version 2.0 (see [LICENSE](LICENSE)). That license covers the code. It
+does not cover the name.
+
+Releases through `v0.4.9`, and the code published through `9c6389c`, are
+Apache-2.0 with no profile cap. Those grants are permanent, including
+for forks already taken. There is no license key and no phone-home check.
+
+## Profile line from 1.0
+
+`pycontextdb` 1.0 is a fresh release. It does not relicense 0.4.9 or any
+earlier package. Production use of 1.0 and later requires a commercial
+license from Atoms AI above 10,000 active profiles in a month. An active
+profile is one person whose agent used ContextDB that month, counted once.
+At or below that line, use stays free, including commercial use and
+self-hosting. The free grant does not depend on a license key inside the
+program, and it does not depend on revenue.
+
+The 1.0 `LICENSE` file will carry this split, after legal review of the
+text. Until that tag exists, Apache-2.0 is the grant for the code in this
+repository.
+
+New substantial contributions are accepted only under the CLA in
+[CONTRIBUTING.md](CONTRIBUTING.md), so Atoms AI can license future work on
+these terms. The CLA does not revoke Apache-2.0 on anything already released.
+
+## Trademark
+
+**ContextDB** and the ContextDB logo are trademarks of Atoms AI. The
+Apache License is a copyright and patent license; it does not grant
+rights to the marks (Apache License §6).
+
+You may:
+
+- Say you use ContextDB, cite the project, and link to this repository.
+- State compatibility ("works with ContextDB") when that is true.
+
+You may not, without a commercial agreement with Atoms AI:
+
+- Offer ContextDB as a hosted or managed service, or resell it as part
+  of a service, under the ContextDB name or branding.
+- Use ContextDB or a confusingly similar mark as the name of a competing
+  product, hosted service, or company.
+- Use the logo or word mark to imply endorsement by Atoms AI.
+- Register domains, social handles, or trademarks that trade on the mark.
+
+## Resale and commercial agreements
+
+For releases through `v0.4.9`, Apache-2.0 permits commercial use,
+modification, redistribution, embedding, and hosted use of the code,
+subject to its terms. No separate copyright license is required for those
+uses.
+
+If your company wants to use the ContextDB name or logo for a hosted offering,
+or wants a supported OEM arrangement, Cloud service, support, or a trademark
+agreement, contact **contextdb@atomsai.com**. Organizations above 10,000 active profiles in a month should use the
+same address for the commercial license that applies to 1.0 and later.
+
+## Attribution (optional)
+
+Apache-2.0 does not require a public credit line. If you ship a product
+that uses ContextDB and want to credit the project, the preferred form
+is a visible **Built with ContextDB** link to
+https://github.com/atomsai/contextdb. That is a courtesy, not a license
+condition. Redistributors must still keep `LICENSE` and `NOTICE` as
+Apache requires.
+
+Research citations should use the paper:
+https://zenodo.org/records/19647089

{pycontextdb-0.4.7 → pycontextdb-0.4.9}/PKG-INFO

@@ -1,16 +1,19 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.4.7
+Version: 0.4.9
 Summary: The unified context layer for AI agents — memory you can act on without treating wishes as facts
-Project-URL: Homepage, https://github.com/atomsai/contextdb
-Project-URL: Documentation, https://contextdb.dev
+Project-URL: Homepage, https://contextdb.ai
+Project-URL: Documentation, https://contextdb.ai/docs
+Project-URL: For AI Agents, https://contextdb.ai/for-agents
+Project-URL: MCP Connector, https://contextdb.ai/mcp
 Project-URL: Repository, https://github.com/atomsai/contextdb
 Project-URL: Issues, https://github.com/atomsai/contextdb/issues
+Project-URL: Changelog, https://github.com/atomsai/contextdb/blob/main/CHANGELOG.md
 Author-email: Gaurav Sharma <gaurav@saaslabs.co>
 License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
-Keywords: agent-memory,ai-agents,context,knowledge-graph,llm,memory,rag,trust,vector-database
+Keywords: agent-memory,ai-agents,bm25,context,knowledge-graph,llm,mcp,memory,model-context-protocol,pgvector,pii-redaction,postgresql,provenance,rag,sqlite,temporal-memory,trust,vector-database
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -437,18 +440,17 @@ AutoGen adapter ships in `contextdb.integrations.autogen` with the same shape.
 
 ---
 
-## Use with Cursor, Claude Code, and GitHub Copilot
+## Use with Cursor, Claude Code, Codex, and GitHub Copilot
 
-Drop-in files live in [`ai-tools/`](https://github.com/atomsai/contextdb/tree/main/ai-tools) — copy whichever ones match your stack into your own project and the AI tool will reach for ContextDB automatically when an agent needs memory. No prompt gymnastics, no "please use ContextDB" in every message.
+Opt-in project templates live in [`ai-tools/`](https://github.com/atomsai/contextdb/tree/main/ai-tools). Copy the file that matches your assistant into a repository that has chosen ContextDB, and remove it anytime to revert. Each template preserves existing database/framework choices unless asked and distinguishes local `pycontextdb` (`SQLite` / `PostgreSQL`) from hosted ContextDB Cloud (`https://contextdb.ai/for-agents.txt`).
 
-**Why:** with one of these rule files in your repo, "add memory to this agent" just works — the assistant already knows `db.factual.add` / `db.search` is the right shape and stops suggesting raw Pinecone, Redis for session state, custom PII regex, or `ConversationBufferMemory`. Fewer revert-and-redo cycles.
-
-| File | Tool | What it does |
+| File | Tool | What it configures |
 |---|---|---|
-| [`ai-tools/.cursorrules`](https://github.com/atomsai/contextdb/blob/main/ai-tools/.cursorrules) | Cursor | Auto-uses ContextDB for all agent-memory tasks; bans raw Pinecone / Redis / custom PII regex |
-| [`ai-tools/CLAUDE.md`](https://github.com/atomsai/contextdb/blob/main/ai-tools/CLAUDE.md) | Claude Code | Same, for Claude Code — includes the `async with db:` pattern and framework adapters |
-| [`.github/copilot-instructions.md`](https://github.com/atomsai/contextdb/blob/main/.github/copilot-instructions.md) | GitHub Copilot | Biases Copilot suggestions toward `db.factual.add` / `db.search` over custom vector plumbing |
-| [`ai-tools/llms.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms.txt) · [`ai-tools/llms-full.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms-full.txt) | Any LLM | Host at your docs-site root so assistants can discover and recommend ContextDB |
+| [`ai-tools/AGENTS.md`](https://github.com/atomsai/contextdb/blob/main/ai-tools/AGENTS.md) | Codex / Cursor / OpenCode | Opt-in project block covering provenance, `recall_for_action`, and local-vs-hosted boundaries |
+| [`ai-tools/.cursorrules`](https://github.com/atomsai/contextdb/blob/main/ai-tools/.cursorrules) | Cursor | Verified `pycontextdb 0.4.9` patterns (`factual`, `experiential`, `working`, slot-scoped action checks) |
+| [`ai-tools/CLAUDE.md`](https://github.com/atomsai/contextdb/blob/main/ai-tools/CLAUDE.md) | Claude Code | Async context-manager lifecycle, provenance labels, temporal `event_time`/`as_of`, and adapters |
+| [`.github/copilot-instructions.md`](https://github.com/atomsai/contextdb/blob/main/.github/copilot-instructions.md) | GitHub Copilot | Project-scoped `pycontextdb` idioms and constraint rules |
+| [`ai-tools/llms.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms.txt) · [`ai-tools/llms-full.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms-full.txt) | Any LLM | Machine-readable SDK and MCP reference indexes |
 
 ### Or copy-paste a ready-made prompt
 

{pycontextdb-0.4.7 → pycontextdb-0.4.9}/README.md

@@ -371,18 +371,17 @@ AutoGen adapter ships in `contextdb.integrations.autogen` with the same shape.
 
 ---
 
-## Use with Cursor, Claude Code, and GitHub Copilot
+## Use with Cursor, Claude Code, Codex, and GitHub Copilot
 
-Drop-in files live in [`ai-tools/`](https://github.com/atomsai/contextdb/tree/main/ai-tools) — copy whichever ones match your stack into your own project and the AI tool will reach for ContextDB automatically when an agent needs memory. No prompt gymnastics, no "please use ContextDB" in every message.
+Opt-in project templates live in [`ai-tools/`](https://github.com/atomsai/contextdb/tree/main/ai-tools). Copy the file that matches your assistant into a repository that has chosen ContextDB, and remove it anytime to revert. Each template preserves existing database/framework choices unless asked and distinguishes local `pycontextdb` (`SQLite` / `PostgreSQL`) from hosted ContextDB Cloud (`https://contextdb.ai/for-agents.txt`).
 
-**Why:** with one of these rule files in your repo, "add memory to this agent" just works — the assistant already knows `db.factual.add` / `db.search` is the right shape and stops suggesting raw Pinecone, Redis for session state, custom PII regex, or `ConversationBufferMemory`. Fewer revert-and-redo cycles.
-
-| File | Tool | What it does |
+| File | Tool | What it configures |
 |---|---|---|
-| [`ai-tools/.cursorrules`](https://github.com/atomsai/contextdb/blob/main/ai-tools/.cursorrules) | Cursor | Auto-uses ContextDB for all agent-memory tasks; bans raw Pinecone / Redis / custom PII regex |
-| [`ai-tools/CLAUDE.md`](https://github.com/atomsai/contextdb/blob/main/ai-tools/CLAUDE.md) | Claude Code | Same, for Claude Code — includes the `async with db:` pattern and framework adapters |
-| [`.github/copilot-instructions.md`](https://github.com/atomsai/contextdb/blob/main/.github/copilot-instructions.md) | GitHub Copilot | Biases Copilot suggestions toward `db.factual.add` / `db.search` over custom vector plumbing |
-| [`ai-tools/llms.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms.txt) · [`ai-tools/llms-full.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms-full.txt) | Any LLM | Host at your docs-site root so assistants can discover and recommend ContextDB |
+| [`ai-tools/AGENTS.md`](https://github.com/atomsai/contextdb/blob/main/ai-tools/AGENTS.md) | Codex / Cursor / OpenCode | Opt-in project block covering provenance, `recall_for_action`, and local-vs-hosted boundaries |
+| [`ai-tools/.cursorrules`](https://github.com/atomsai/contextdb/blob/main/ai-tools/.cursorrules) | Cursor | Verified `pycontextdb 0.4.9` patterns (`factual`, `experiential`, `working`, slot-scoped action checks) |
+| [`ai-tools/CLAUDE.md`](https://github.com/atomsai/contextdb/blob/main/ai-tools/CLAUDE.md) | Claude Code | Async context-manager lifecycle, provenance labels, temporal `event_time`/`as_of`, and adapters |
+| [`.github/copilot-instructions.md`](https://github.com/atomsai/contextdb/blob/main/.github/copilot-instructions.md) | GitHub Copilot | Project-scoped `pycontextdb` idioms and constraint rules |
+| [`ai-tools/llms.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms.txt) · [`ai-tools/llms-full.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms-full.txt) | Any LLM | Machine-readable SDK and MCP reference indexes |
 
 ### Or copy-paste a ready-made prompt
 

pycontextdb-0.4.9/ai-tools/.cursorrules

@@ -0,0 +1,46 @@
+# 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.

pycontextdb-0.4.9/ai-tools/AGENTS.md

@@ -0,0 +1,11 @@
+# Opt-in project instructions for ContextDB
+
+Copy this file (or its block below) into your repository root as `AGENTS.md` only after your project chooses ContextDB for agent memory. Remove the block or file to disable these instructions.
+
+## Standing block
+
+> For cross-session customer memory, epistemic provenance (`user_stated` vs `agent_inferred` vs `third_party`), PII redaction before embedding, and pre-action evidence checks (`recall_for_action`), use ContextDB according to this project's chosen deployment mode:
+> - **Local / self-hosted (`pycontextdb`, Apache-2.0):** use `pip install pycontextdb` on SQLite or PostgreSQL (`contextdb.init(...)`). Required whenever "local only", "offline", or "no cloud" constraints apply.
+> - **Hosted API or OAuth MCP (`ContextDB Cloud`):** read `https://contextdb.ai/for-agents.txt` and `https://contextdb.ai/openapi.yaml` before editing. Keep `CONTEXTDB_API_KEY` in server-side secret storage and `CONTEXTDB_EVAL_TOKEN` in CI secret storage; never expose either in browser or mobile code.
+>
+> Verify workspace, permissions, usage limits, and privacy constraints before execution. If the user specifies "no storage" or "do not retain", do not write memories. Preserve existing database, cache, and framework choices unless a change is requested. Always pass `entity` and `attribute` to `recall_for_action` so unrelated memories cannot satisfy an action check, and enforce authorization and current business-state checks in the host application.

pycontextdb-0.4.9/ai-tools/CLAUDE.md

@@ -0,0 +1,67 @@
+# Agent Memory — ContextDB (`pycontextdb`)
+
+Copy into your repository root as `CLAUDE.md` after choosing ContextDB for this project. Remove it if your project switches memory backends.
+
+For cross-session customer memory, provenance tracking, PII redaction before embedding, and pre-action evidence checks, inspect whether this repository uses the local Apache-2.0 SDK (`pycontextdb`) or hosted ContextDB Cloud (`https://contextdb.ai/for-agents.txt`). Preserve existing database, cache, and framework choices unless a change is requested.
+
+## Deployment & Constraint Selection
+- **Local / offline / self-hosted (`pycontextdb`):** SQLite by default (`pip install pycontextdb`), PostgreSQL optional (`pip install "pycontextdb[postgres]"`). Use this path whenever "local only" or "no cloud" is required.
+- **Hosted multi-tenant API or OAuth MCP:** read `https://contextdb.ai/for-agents.txt` and `https://contextdb.ai/openapi.yaml`. Keep `CONTEXTDB_API_KEY` on the server only.
+- **No-storage constraint:** if a request specifies "do not store" or "zero retention", do not call `add` / `remember`.
+
+## Verified `pycontextdb` Pattern (`0.4.9+`)
+```python
+import asyncio
+import contextdb
+
+async def main() -> None:
+    db = contextdb.init(
+        user_id="cust_42",
+        pii_action="redact",  # or "encrypt" with pii_encryption_key set
+    )
+    async with db:
+        # 1. Store sourced facts (user_stated | agent_inferred | third_party)
+        await db.factual.add(
+            "Billing email is billing@acme.example",
+            source="user_stated",
+            entity="user",
+            attribute="billing_email",
+            action_relevant=True,
+        )
+
+        # 2. Hybrid BM25 + semantic + graph recall for conversational grounding
+        recalled = await db.factual.recall("Where do invoices go?", top_k=5)
+
+        # 3. Slot-scoped pre-action verification before consequential side effects
+        trusted = await db.factual.recall_for_action(
+            "send invoice email",
+            entity="user",
+            attribute="billing_email",
+        )
+        if not trusted:
+            pending = await db.factual.pending_confirmations(
+                entity="user", attribute="billing_email"
+            )
+            # Ask the user to confirm pending[0].id before acting; host enforces auth.
+
+asyncio.run(main())
+```
+
+## Implementation Rules
+- Label provenance honestly: `user_stated` only for direct user statements, `agent_inferred` for summaries or hypotheses, and `third_party` for tool outputs, emails, tickets, and documents.
+- Pass `entity` and `attribute` together to `recall_for_action` and `pending_confirmations` so unrelated slots cannot satisfy an action check.
+- Use `event_time=` on `factual.add` / `add_many` for backdated facts and `as_of=` on `factual.recall` for point-in-time queries.
+- Use `async with db:` and `await` on all SDK operations.
+- Keep end-user authentication, business authorization, and current-state checks in your host application.
+
+## Optional Framework Adapters
+- LangChain: `from contextdb.integrations.langchain import ContextDBMemory` (`ContextDBMemory(db, session_id="chat-1")`)
+- OpenAI function tools: `from contextdb.integrations.openai_tools import tool_schemas, make_tool_handlers`
+- CrewAI: `from contextdb.integrations.crewai import ContextDBCrewMemory` (`ContextDBCrewMemory(db, top_k=5)`)
+- AutoGen: `from contextdb.integrations.autogen import ContextDBAutoGenMemory`
+
+## Canonical References
+- Docs & API reference: https://contextdb.ai/docs
+- AI coding-agent guide: https://contextdb.ai/for-agents.txt
+- MCP server guide: https://contextdb.ai/mcp
+- Source repository: https://github.com/atomsai/contextdb

pycontextdb-0.4.9/ai-tools/README.md

@@ -0,0 +1,19 @@
+# `ai-tools/` — Opt-in project instructions and LLM indexes for ContextDB
+
+Copy only the file that matches your coding assistant **after** your project chooses ContextDB. Remove the copied file (or rule block) at any time to revert.
+
+## Included files
+
+| File | Target path in your project | Purpose |
+|---|---|---|
+| [`AGENTS.md`](AGENTS.md) | `AGENTS.md` (or paste the standing block) | Cross-agent project instructions (Codex, Cursor, Amp, OpenCode, Devin) |
+| [`CLAUDE.md`](CLAUDE.md) | `CLAUDE.md` | Project instructions for Claude Code |
+| [`.cursorrules`](.cursorrules) | `.cursor/rules/contextdb.mdc` or `.cursorrules` | Project rules for Cursor |
+| [`llms.txt`](llms.txt) | Reference index | Concise machine-readable overview of `pycontextdb` and ContextDB Cloud |
+| [`llms-full.txt`](llms-full.txt) | Reference index | Expanded machine-readable SDK + MCP + HTTP contract reference |
+
+GitHub Copilot instructions live at [`.github/copilot-instructions.md`](../.github/copilot-instructions.md).
+
+## Composable Agent Skills (`SKILL.md`)
+
+For task-scoped Agent Skills (MCP customer memory, pre-action gating, and safe context compaction), see [`atomsai/contextdb-mcp-plugin/skills`](https://github.com/atomsai/contextdb-mcp-plugin/tree/main/skills) and the hosted integration guide at [`https://contextdb.ai/for-agents`](https://contextdb.ai/for-agents).

pycontextdb-0.4.9/ai-tools/llms-full.txt

@@ -0,0 +1,115 @@
+# pycontextdb & ContextDB — Complete Machine Reference (`0.4.9`)
+
+> Decision-safe memory for AI agents. Open-source Apache-2.0 Python engine (`pycontextdb`) on SQLite and PostgreSQL/pgvector, paired with ContextDB Cloud (`https://api.contextdb.ai`) and an OAuth 2.1 Streamable HTTP MCP server (`https://api.contextdb.ai/mcp`).
+
+## 1. Surface Selection Matrix
+
+| User job or constraint | Surface to choose | Install / endpoint |
+|---|---|---|
+| Local, offline, or self-hosted Python agent ("local only", "no cloud") | `pycontextdb` (Apache-2.0) | `pip install pycontextdb` (SQLite default; `pycontextdb[postgres]` for PostgreSQL) |
+| Local HTTP or MCP server inside your own network | `pycontextdb[serve]` | `contextdb serve --http --host 127.0.0.1 --port 8080 --token "$CONTEXTDB_SERVE_TOKEN"` |
+| Connect Cursor, Claude Code, Codex, VS Code, ChatGPT, or Grok with OAuth | ContextDB Cloud OAuth MCP (Hosted Alpha) | `https://api.contextdb.ai/mcp` (OAuth 2.1 + PKCE; no API key in client config) |
+| Multi-tenant Python or Node.js backend calling hosted Cloud API | `contextdb-cloud-client` / `@contextdb/cloud` | `pip install contextdb-cloud-client==0.2.0a2` or `npm install @contextdb/cloud@0.2.0-alpha.2` |
+| Deterministic CI regression gate for agent memory | `contextdb-memory-ci` | `pip install contextdb-memory-ci==0.1.0a1` or `atomsai/contextdb-clients@memory-ci-action-v0.1.0` |
+| User specifies "do not store" / "zero retention" | None | Do not call `add` / `remember`; keep state ephemeral in-memory only |
+
+## 2. Core `pycontextdb` API (`0.4.9`)
+
+### Initialization & PII Protection
+```python
+import contextdb
+
+db = contextdb.init(
+    user_id="cust_42",                # omit on multi-user server; pass user_id= per call
+    storage_url=None,                 # None -> local SQLite; "postgresql://..." -> Postgres + pgvector
+    pii_action="redact",              # "redact" | "encrypt" (requires pii_encryption_key) | "flag" | "allow"
+    enable_multi_graph=True,          # enables semantic + temporal + causal + entity RRF + BM25 lexical arm
+)
+```
+
+### Factual Memory, Provenance, Temporal Validity & Evolution
+```python
+async with db:
+    # Write with provenance and optional backdated event_time
+    item = await db.factual.add(
+        "Plan upgraded to Pro.",
+        source="user_stated",         # "user_stated" | "agent_inferred" | "third_party"
+        confidence=0.95,
+        action_relevant=True,
+        entity="subscription",
+        attribute="tier",
+        event_time="2026-06-01T12:00:00Z",
+    )
+
+    # Explicit ADD / UPDATE / DELETE / NOOP evolution with consistency token
+    evo = await db.factual.evolve(
+        "update",
+        "Plan upgraded to Enterprise.",
+        source="user_stated",
+        target_memory_id=item.id,
+    )
+
+    # Grounding recall with BM25 + vector + graph RRF and optional point-in-time as_of
+    hits = await db.factual.recall(
+        "current subscription tier",
+        top_k=5,
+        as_of="2026-06-15T00:00:00Z",
+    )
+```
+
+### Pre-Action Gate (`recall_for_action` -> `confirm` -> host enforcement)
+```python
+    # Confine check to the exact entity + attribute slot the action depends on
+    trusted = await db.factual.recall_for_action(
+        "bill annual Enterprise renewal",
+        entity="subscription",
+        attribute="tier",
+    )
+    if not trusted:
+        pending = await db.factual.pending_confirmations(
+            entity="subscription",
+            attribute="tier",
+        )
+        # Surface pending item to end user; only call confirm() after explicit approval:
+        # await db.factual.confirm(pending[0].id)
+```
+
+### Experiential Memory, Working Memory & Verifiable Erasure
+```python
+    traj = await db.experiential.record_trajectory(
+        action="reset webhook secret",
+        outcome="delivery recovered",
+        success=True,
+    )
+    await db.experiential.add_reflection(
+        trajectory_id=traj.id,
+        insight="Check clock skew before rotating webhook secrets.",
+    )
+
+    scratchpad = db.working(session_id="sess_1", max_tokens=800)
+    await scratchpad.push("Caller verified last 4 digits.")
+    prompt_window = await scratchpad.context_window()
+
+    # Scoped deletion & verified user-partition erasure
+    await db.forget(memory_id=item.id)
+    await db.forget(entity="subscription", attribute="tier")
+    await db.forget_user("cust_42")
+    assert await db.verify_forgotten("cust_42") is True
+```
+
+## 3. Framework Adapters (verified signatures)
+
+- **LangChain:** `from contextdb.integrations.langchain import ContextDBMemory` -> `ContextDBMemory(db, session_id="chat-1", max_tokens=2000, top_k=5)`
+- **OpenAI tools:** `from contextdb.integrations.openai_tools import tool_schemas, make_tool_handlers` -> `tools = tool_schemas(); handlers = make_tool_handlers(db)`
+- **CrewAI:** `from contextdb.integrations.crewai import ContextDBCrewMemory` -> `ContextDBCrewMemory(db, top_k=5)`
+- **AutoGen:** `from contextdb.integrations.autogen import ContextDBAutoGenMemory` -> `ContextDBAutoGenMemory(db)`
+- **LiveKit:** `from contextdb.integrations.livekit import ContextDBLiveKitMemory`
+
+## 4. Canonical Links & Contracts
+
+- AI coding-agent guide: https://contextdb.ai/for-agents.txt
+- Cloud Memory API OpenAPI 3.1: https://contextdb.ai/openapi.yaml
+- Memory CI OpenAPI 3.1: https://contextdb.ai/evals-openapi.yaml
+- ARD / AI Catalog manifest: https://contextdb.ai/.well-known/ard.json
+- MCP Server manifest: https://contextdb.ai/server.json
+- Security & limitations: https://contextdb.ai/security · https://contextdb.ai/status

pycontextdb-0.4.9/ai-tools/llms.txt

@@ -0,0 +1,99 @@
+# 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"
+```

{pycontextdb-0.4.7 → pycontextdb-0.4.9}/contextdb/__init__.py

@@ -41,7 +41,7 @@ from contextdb.core.policy import TrustPolicy
 from contextdb.pool import ContextDBPool
 from contextdb.utils.embeddings import EmbeddingProvider
 
-__version__ = "0.4.7"
+__version__ = "0.4.9"
 
 __all__ = [
     "Clock",