cortexdb-ag2 0.1.0__tar.gz

cortexdb_ag2-0.1.0/.gitignore

@@ -0,0 +1,79 @@
+# Rust
+/target
+**/*.rs.bk
+
+# Environment / secrets
+.env
+.env.local
+.env*.local
+*.pem
+*.key
+.npmrc
+
+# SQLite database
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Data directories
+cortexdb_data*/
+/data/
+# Per-bench tenant stores (RocksDB + Tantivy + HNSW state; regeneratable per run)
+/data_*/
+# Experimental per-branch stores (not tracked on this branch but left gitignored
+# so checkout from other branches doesn't surface them in git status)
+/event_memory_store/
+/llm_cache/
+
+# Benchmark inputs and per-run outputs (kept local, regenerated each run)
+benchmarks/longmemeval/data/
+benchmarks/longmemeval/server_results/
+benchmarks/longmemeval/fast_results/
+benchmarks/longmemeval/micro_results/
+benchmarks/longmemeval/server_logs/
+benchmarks/longmemeval/*.log
+benchmarks/locomo/locomo_results*.json
+benchmarks/locomo/server_results/
+benchmarks/locomo/*.log
+/answer_out.json
+
+# Local Claude Code state
+.claude/
+.tmp/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# Node
+node_modules/
+dist/
+.next/
+
+# Egg info
+*.egg-info/
+
+# Scratch/debug text files at root
+/*.txt
+/*.log
+
+# Local debug / marketing / private content (not for repo)
+harness/.reports/
+harness_data_*/
+blog/
+sales/
+videos/
+local-instance/

cortexdb_ag2-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: cortexdb-ag2
+Version: 0.1.0
+Summary: AG2 integration for CortexDB — long-term memory for AI agent conversations
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: ag2>=0.4
+Requires-Dist: cortexdbai>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cortexdb-ag2
+
+AG2 (formerly AutoGen) integration for CortexDB long-term memory.
+
+> **LLM provider note (audit BLK-2):** the canonical example shows GPT-4o
+> in the AG2 LLM config. CortexDB itself is LLM-agnostic. Swap providers
+> through AG2's standard `llm_config` — Anthropic, Gemini, Mistral, and
+> Together AI all work. Nothing in `cortexdb-ag2` reads `OPENAI_API_KEY`.
+
+## Install
+
+```bash
+pip install cortexdb-ag2
+```
+
+## API base URL
+
+Defaults to `https://api-v1.cortexdb.ai` (audit FRI-8). Override with
+`CORTEXDB_API_URL`.

cortexdb_ag2-0.1.0/README.md

@@ -0,0 +1,19 @@
+# cortexdb-ag2
+
+AG2 (formerly AutoGen) integration for CortexDB long-term memory.
+
+> **LLM provider note (audit BLK-2):** the canonical example shows GPT-4o
+> in the AG2 LLM config. CortexDB itself is LLM-agnostic. Swap providers
+> through AG2's standard `llm_config` — Anthropic, Gemini, Mistral, and
+> Together AI all work. Nothing in `cortexdb-ag2` reads `OPENAI_API_KEY`.
+
+## Install
+
+```bash
+pip install cortexdb-ag2
+```
+
+## API base URL
+
+Defaults to `https://api-v1.cortexdb.ai` (audit FRI-8). Override with
+`CORTEXDB_API_URL`.

cortexdb_ag2-0.1.0/cortexdb_ag2/__init__.py

@@ -0,0 +1,21 @@
+"""CortexDB integration for AG2 (successor to AutoGen).
+
+Provides a memory-augmented agent mixin and callable tools that connect
+AG2's multi-agent framework to CortexDB's long-term memory system.
+"""
+
+from cortexdb_ag2.agent import CortexDBAgent
+from cortexdb_ag2.tools import (
+    cortexdb_forget_fn,
+    cortexdb_search_fn,
+    cortexdb_store_fn,
+    register_cortexdb_tools,
+)
+
+__all__ = [
+    "CortexDBAgent",
+    "cortexdb_search_fn",
+    "cortexdb_store_fn",
+    "cortexdb_forget_fn",
+    "register_cortexdb_tools",
+]

cortexdb_ag2-0.1.0/cortexdb_ag2/agent.py

@@ -0,0 +1,183 @@
+"""AG2 agent with built-in CortexDB memory.
+
+Provides a ConversableAgent subclass that automatically stores
+conversation turns and retrieves relevant context from CortexDB
+before generating responses. Compatible with AG2 (the successor
+to Microsoft AutoGen).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+
+from autogen import ConversableAgent
+
+from cortexdb import Cortex
+
+
+class CortexDBAgent(ConversableAgent):
+    """AG2 ConversableAgent with automatic CortexDB memory integration.
+
+    Extends AG2's ConversableAgent to automatically store conversation
+    turns in CortexDB and retrieve relevant past context before generating
+    responses. This enables the agent to maintain long-term memory across
+    conversations and sessions.
+
+    The agent injects retrieved context as a system-level prefix to the
+    conversation, giving the LLM access to relevant memories without
+    modifying the visible chat history.
+
+    Args:
+        name: The agent's name.
+        cortex_client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+        auto_store: Whether to automatically store conversation turns.
+            Defaults to ``True``.
+        auto_recall: Whether to automatically retrieve context before
+            responding. Defaults to ``True``.
+        **kwargs: Additional keyword arguments passed to ConversableAgent.
+
+    Example::
+
+        from cortexdb import Cortex
+        from cortexdb_ag2 import CortexDBAgent
+
+        client = Cortex("http://localhost:3141")
+        agent = CortexDBAgent(
+            name="memory_assistant",
+            cortex_client=client,
+            scope="user:default",
+            llm_config=llm_config,
+            system_message="You are a helpful assistant with long-term memory.",
+        )
+    """
+
+    def __init__(
+        self,
+        name: str,
+        cortex_client: Cortex,
+        scope: str = "user:default",
+        auto_store: bool = True,
+        auto_recall: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(name=name, **kwargs)
+        self._cortex_client = cortex_client
+        self._scope = scope
+        self._auto_store = auto_store
+        self._auto_recall = auto_recall
+
+    def generate_reply(
+        self,
+        messages: Optional[list[dict[str, Any]]] = None,
+        sender: Optional[Any] = None,
+        **kwargs: Any,
+    ) -> Union[str, dict[str, Any], None]:
+        """Generate a reply with CortexDB memory augmentation.
+
+        Before generating a reply, retrieves relevant context from CortexDB
+        based on the latest message. After generating, stores the conversation
+        turn for future recall.
+
+        Args:
+            messages: The conversation messages to respond to.
+            sender: The agent that sent the message.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The generated reply string, a structured reply dict, or None.
+        """
+        if messages and self._auto_recall:
+            latest_message = messages[-1]
+            content = latest_message.get("content", "")
+            if content:
+                context = self._recall_context(str(content))
+                if context:
+                    messages = self._inject_memory_context(messages, context)
+
+        reply = super().generate_reply(messages=messages, sender=sender, **kwargs)
+
+        if reply and self._auto_store and messages:
+            latest_content = messages[-1].get("content", "") if messages else ""
+            reply_text = reply if isinstance(reply, str) else reply.get("content", "")
+            if latest_content and reply_text:
+                self._store_turn(str(latest_content), str(reply_text))
+
+        return reply
+
+    def _recall_context(self, query: str) -> str:
+        """Retrieve relevant context from CortexDB.
+
+        Args:
+            query: The query to search for relevant memories.
+
+        Returns:
+            The context string from CortexDB, or empty string on failure.
+        """
+        try:
+            result = self._cortex_client.recall(
+                self._scope,
+                query=query,
+            )
+        except Exception:
+            return ""
+
+        return result.get("context_block", "") if result else ""
+
+    def _store_turn(self, user_message: str, assistant_reply: str) -> None:
+        """Store a conversation turn in CortexDB.
+
+        Args:
+            user_message: The user's message.
+            assistant_reply: The agent's reply.
+        """
+        content = f"User: {user_message}\nAssistant: {assistant_reply}"
+        try:
+            self._cortex_client.experience(self._scope, text=content)
+        except Exception:
+            pass
+
+    def _inject_memory_context(
+        self,
+        messages: list[dict[str, Any]],
+        context: str,
+    ) -> list[dict[str, Any]]:
+        """Inject retrieved memory context into the message list.
+
+        Prepends a system message containing the retrieved context
+        so the LLM can reference it when generating a response.
+
+        Args:
+            messages: The original conversation messages.
+            context: The retrieved context string from CortexDB.
+
+        Returns:
+            A new message list with the memory context injected.
+        """
+        context_message = {
+            "role": "system",
+            "content": (
+                f"Relevant context from long-term memory:\n\n{context}\n\n"
+                "Use this context to inform your response if relevant."
+            ),
+        }
+
+        augmented = list(messages)
+        augmented.insert(0, context_message)
+        return augmented
+
+    def clear_memory(self) -> dict[str, Any]:
+        """Clear all memories for this agent's scope.
+
+        Removes all stored memories from CortexDB for the configured
+        scope path.
+
+        Returns:
+            The forget response dict from CortexDB.
+        """
+        return self._cortex_client.forget(
+            self._scope,
+            confirm_all=True,
+            cascade="redact_events",
+            reason="AG2 agent memory clear requested",
+        )

cortexdb_ag2-0.1.0/cortexdb_ag2/tools.py

@@ -0,0 +1,165 @@
+"""AG2 callable tools for interacting with CortexDB.
+
+Provides factory functions that create CortexDB-backed callables
+suitable for registration with AG2's ConversableAgent tool system.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Callable, Optional
+
+from cortexdb import Cortex
+
+
+def cortexdb_search_fn(
+    client: Cortex,
+    scope: str = "user:default",
+) -> Callable[..., str]:
+    """Create a search function for use as an AG2 tool.
+
+    Returns a callable that performs semantic recall over CortexDB's
+    memory store, suitable for registration with an AG2 agent.
+
+    Args:
+        client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+
+    Returns:
+        A callable function that accepts a ``query`` parameter and
+        returns the recalled context block.
+
+    Example::
+
+        from cortexdb import Cortex
+        from cortexdb_ag2 import cortexdb_search_fn
+
+        client = Cortex("http://localhost:3141")
+        search = cortexdb_search_fn(client, scope="user:default")
+
+        agent.register_for_llm(description="Search memories")(search)
+        user_proxy.register_for_execution()(search)
+    """
+
+    def search(
+        query: Annotated[str, "The search query to find relevant memories."],
+    ) -> str:
+        """Search CortexDB for relevant memories and past context."""
+        result = client.recall(scope, query=query)
+
+        context = result.get("context_block", "") if result else ""
+        if not context:
+            return "No relevant memories found."
+
+        return context
+
+    search.__name__ = "cortexdb_search"
+    search.__doc__ = "Search CortexDB for relevant memories and past context."
+    return search
+
+
+def cortexdb_store_fn(
+    client: Cortex,
+    scope: str = "user:default",
+) -> Callable[..., str]:
+    """Create a store function for use as an AG2 tool.
+
+    Returns a callable that persists information into CortexDB's
+    long-term memory, suitable for registration with an AG2 agent.
+
+    Args:
+        client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+
+    Returns:
+        A callable function that accepts a ``content`` parameter and
+        returns a confirmation message.
+    """
+
+    def store(
+        content: Annotated[str, "The content to store as a memory."],
+    ) -> str:
+        """Store information in CortexDB's long-term memory."""
+        client.experience(scope, text=content)
+        return "Memory stored successfully in CortexDB."
+
+    store.__name__ = "cortexdb_store"
+    store.__doc__ = "Store information in CortexDB's long-term memory."
+    return store
+
+
+def cortexdb_forget_fn(
+    client: Cortex,
+    scope: str = "user:default",
+) -> Callable[..., str]:
+    """Create a forget function for use as an AG2 tool.
+
+    Returns a callable that removes memories from CortexDB, suitable
+    for registration with an AG2 agent.
+
+    Args:
+        client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+
+    Returns:
+        A callable function that accepts a ``reason`` parameter
+        and returns a confirmation message.
+    """
+
+    def forget(
+        reason: Annotated[str, "The reason for forgetting these memories."],
+    ) -> str:
+        """Forget or remove memories from CortexDB."""
+        client.forget(
+            scope,
+            confirm_all=True,
+            cascade="redact_events",
+            reason=reason,
+        )
+        return f"Memories in scope '{scope}' have been forgotten."
+
+    forget.__name__ = "cortexdb_forget"
+    forget.__doc__ = "Forget or remove memories from CortexDB."
+    return forget
+
+
+def register_cortexdb_tools(
+    agent: Any,
+    executor: Any,
+    client: Cortex,
+    scope: str = "user:default",
+) -> None:
+    """Register all CortexDB tools with an AG2 agent and executor.
+
+    Convenience function that creates and registers search, store, and
+    forget tools on both the LLM-facing agent and the execution proxy.
+
+    Args:
+        agent: The AG2 ConversableAgent that will call the tools.
+        executor: The AG2 agent (typically UserProxyAgent) that
+            executes tool calls.
+        client: An initialized CortexDB client instance.
+        scope: The hierarchical scope path for memory isolation.
+
+    Example::
+
+        from ag2 import ConversableAgent, UserProxyAgent
+        from cortexdb import Cortex
+        from cortexdb_ag2 import register_cortexdb_tools
+
+        client = Cortex("http://localhost:3141")
+        assistant = ConversableAgent("assistant", llm_config=llm_config)
+        user_proxy = UserProxyAgent("user_proxy")
+
+        register_cortexdb_tools(assistant, user_proxy, client, scope="user:default")
+    """
+    search = cortexdb_search_fn(client, scope)
+    store = cortexdb_store_fn(client, scope)
+    forget = cortexdb_forget_fn(client, scope)
+
+    for fn, desc in [
+        (search, "Search CortexDB for relevant memories and past context."),
+        (store, "Store information in CortexDB's long-term memory."),
+        (forget, "Forget or remove memories from CortexDB."),
+    ]:
+        agent.register_for_llm(description=desc)(fn)
+        executor.register_for_execution()(fn)

cortexdb_ag2-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cortexdb-ag2"
+version = "0.1.0"
+description = "AG2 integration for CortexDB — long-term memory for AI agent conversations"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = [
+    "cortexdbai>=0.1.0",
+    "ag2>=0.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]

cortexdb_ag2-0.1.0/tests/test_agent.py

@@ -0,0 +1,182 @@
+"""Tests for the CortexDBAgent AG2 integration.
+
+Validates that the memory-augmented ConversableAgent subclass correctly
+stores turns, recalls context, injects memories, and respects its
+configuration flags against the v1 SDK surface.
+"""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from unittest.mock import MagicMock, patch
+
+
+class _MockConversableAgent:
+    """Minimal stand-in for ag2.ConversableAgent."""
+
+    def __init__(self, name: str = "", **kwargs):
+        self.name = name
+        self._kwargs = kwargs
+
+    def generate_reply(self, messages=None, sender=None, **kwargs):
+        return "mock reply"
+
+
+mock_ag2 = MagicMock()
+mock_ag2.ConversableAgent = _MockConversableAgent
+
+mock_cortexdb = MagicMock()
+mock_cortexdb.Cortex = MagicMock()
+
+with patch.dict(sys.modules, {
+    "ag2": mock_ag2,
+    "cortexdb": mock_cortexdb,
+}):
+    from cortexdb_ag2.agent import CortexDBAgent
+
+
+class TestCortexDBAgentInit(unittest.TestCase):
+    """Tests for CortexDBAgent construction."""
+
+    def test_sets_scope(self) -> None:
+        client = MagicMock()
+        agent = CortexDBAgent(
+            name="test",
+            cortex_client=client,
+            scope="org:acme/user:bob",
+        )
+        self.assertEqual(agent._scope, "org:acme/user:bob")
+        self.assertIs(agent._cortex_client, client)
+
+    def test_defaults(self) -> None:
+        client = MagicMock()
+        agent = CortexDBAgent(name="test", cortex_client=client)
+        self.assertEqual(agent._scope, "user:default")
+        self.assertTrue(agent._auto_store)
+        self.assertTrue(agent._auto_recall)
+
+    def test_auto_flags(self) -> None:
+        client = MagicMock()
+        agent = CortexDBAgent(
+            name="test", cortex_client=client,
+            auto_store=False, auto_recall=False,
+        )
+        self.assertFalse(agent._auto_store)
+        self.assertFalse(agent._auto_recall)
+
+
+class TestRecallContext(unittest.TestCase):
+    """Tests for _recall_context."""
+
+    def setUp(self) -> None:
+        self.client = MagicMock()
+        self.agent = CortexDBAgent(
+            name="test", cortex_client=self.client, scope="user:t1",
+        )
+
+    def test_calls_recall(self) -> None:
+        self.client.recall.return_value = {"context_block": "mem1"}
+        result = self.agent._recall_context("query")
+        self.client.recall.assert_called_once_with("user:t1", query="query")
+        self.assertEqual(result, "mem1")
+
+    def test_handles_empty_context(self) -> None:
+        self.client.recall.return_value = {"context_block": ""}
+        result = self.agent._recall_context("q")
+        self.assertEqual(result, "")
+
+    def test_handles_exception_gracefully(self) -> None:
+        self.client.recall.side_effect = ConnectionError("offline")
+        result = self.agent._recall_context("q")
+        self.assertEqual(result, "")
+
+
+class TestStoreTurn(unittest.TestCase):
+    """Tests for _store_turn."""
+
+    def setUp(self) -> None:
+        self.client = MagicMock()
+        self.agent = CortexDBAgent(
+            name="test", cortex_client=self.client, scope="user:t1",
+        )
+
+    def test_calls_experience_with_formatted_content(self) -> None:
+        self.agent._store_turn("user msg", "assistant reply")
+        self.client.experience.assert_called_once_with(
+            "user:t1",
+            text="User: user msg\nAssistant: assistant reply",
+        )
+
+    def test_handles_exception_gracefully(self) -> None:
+        self.client.experience.side_effect = RuntimeError("fail")
+        self.agent._store_turn("u", "a")
+
+
+class TestInjectMemoryContext(unittest.TestCase):
+    """Tests for _inject_memory_context."""
+
+    def setUp(self) -> None:
+        self.client = MagicMock()
+        self.agent = CortexDBAgent(name="test", cortex_client=self.client)
+
+    def test_prepends_system_message(self) -> None:
+        messages = [{"role": "user", "content": "hello"}]
+        result = self.agent._inject_memory_context(messages, "memory one")
+        self.assertEqual(len(result), 2)
+        self.assertEqual(result[0]["role"], "system")
+        self.assertIn("memory one", result[0]["content"])
+
+    def test_does_not_mutate_original(self) -> None:
+        messages = [{"role": "user", "content": "hi"}]
+        original_len = len(messages)
+        self.agent._inject_memory_context(messages, "m")
+        self.assertEqual(len(messages), original_len)
+
+
+class TestClearMemory(unittest.TestCase):
+    """Tests for clear_memory."""
+
+    def test_calls_forget(self) -> None:
+        client = MagicMock()
+        agent = CortexDBAgent(
+            name="test", cortex_client=client, scope="user:t1",
+        )
+        agent.clear_memory()
+        client.forget.assert_called_once_with(
+            "user:t1",
+            confirm_all=True,
+            cascade="redact_events",
+            reason="AG2 agent memory clear requested",
+        )
+
+
+class TestAutoStoreDisabled(unittest.TestCase):
+    """Tests that auto_store=False skips storing."""
+
+    def test_no_store_when_disabled(self) -> None:
+        client = MagicMock()
+        client.recall.return_value = {"context_block": ""}
+        agent = CortexDBAgent(
+            name="test", cortex_client=client, auto_store=False,
+        )
+        messages = [{"role": "user", "content": "hello"}]
+        agent.generate_reply(messages=messages)
+        client.experience.assert_not_called()
+
+
+class TestAutoRecallDisabled(unittest.TestCase):
+    """Tests that auto_recall=False skips recall."""
+
+    def test_no_recall_when_disabled(self) -> None:
+        client = MagicMock()
+        agent = CortexDBAgent(
+            name="test", cortex_client=client, auto_recall=False,
+        )
+        messages = [{"role": "user", "content": "hello"}]
+        agent.generate_reply(messages=messages)
+        client.recall.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

cortexdb_ag2-0.1.0/tests/test_tools.py

@@ -0,0 +1,155 @@
+"""Tests for AG2 CortexDB tools.
+
+Validates that factory functions produce correctly configured callables
+that delegate to the CortexDB client for search, store, and forget operations.
+"""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from unittest.mock import MagicMock, patch
+
+
+mock_cortexdb = MagicMock()
+mock_cortex_class = MagicMock()
+mock_cortexdb.Cortex = mock_cortex_class
+
+mock_ag2 = MagicMock()
+mock_ag2.ConversableAgent = type(
+    "ConversableAgent", (), {"__init__": lambda self, **kw: None},
+)
+
+with patch.dict(sys.modules, {"cortexdb": mock_cortexdb, "ag2": mock_ag2}):
+    from cortexdb_ag2.tools import (
+        cortexdb_forget_fn,
+        cortexdb_search_fn,
+        cortexdb_store_fn,
+        register_cortexdb_tools,
+    )
+
+
+class TestCortexDBSearchFn(unittest.TestCase):
+    """Tests for the cortexdb_search_fn factory."""
+
+    def setUp(self) -> None:
+        self.client = MagicMock()
+
+    def test_returns_callable(self) -> None:
+        fn = cortexdb_search_fn(self.client)
+        self.assertTrue(callable(fn))
+
+    def test_function_name(self) -> None:
+        fn = cortexdb_search_fn(self.client)
+        self.assertEqual(fn.__name__, "cortexdb_search")
+
+    def test_calls_recall(self) -> None:
+        self.client.recall.return_value = {"context_block": ""}
+        fn = cortexdb_search_fn(self.client, scope="user:t1")
+        fn(query="hello")
+        self.client.recall.assert_called_once_with("user:t1", query="hello")
+
+    def test_with_results_returns_context(self) -> None:
+        self.client.recall.return_value = {"context_block": "memory one"}
+        fn = cortexdb_search_fn(self.client)
+        result = fn(query="test")
+        self.assertEqual(result, "memory one")
+
+    def test_with_no_results(self) -> None:
+        self.client.recall.return_value = {"context_block": ""}
+        fn = cortexdb_search_fn(self.client)
+        result = fn(query="nothing")
+        self.assertEqual(result, "No relevant memories found.")
+
+    def test_default_scope(self) -> None:
+        self.client.recall.return_value = {"context_block": ""}
+        fn = cortexdb_search_fn(self.client)
+        fn(query="q")
+        self.client.recall.assert_called_once_with("user:default", query="q")
+
+
+class TestCortexDBStoreFn(unittest.TestCase):
+    """Tests for the cortexdb_store_fn factory."""
+
+    def setUp(self) -> None:
+        self.client = MagicMock()
+
+    def test_returns_callable(self) -> None:
+        fn = cortexdb_store_fn(self.client)
+        self.assertTrue(callable(fn))
+
+    def test_function_name(self) -> None:
+        fn = cortexdb_store_fn(self.client)
+        self.assertEqual(fn.__name__, "cortexdb_store")
+
+    def test_calls_experience(self) -> None:
+        fn = cortexdb_store_fn(self.client, scope="user:t1")
+        result = fn(content="important fact")
+        self.client.experience.assert_called_once_with(
+            "user:t1", text="important fact",
+        )
+        self.assertIn("stored successfully", result)
+
+    def test_default_scope(self) -> None:
+        fn = cortexdb_store_fn(self.client)
+        fn(content="data")
+        self.client.experience.assert_called_once_with(
+            "user:default", text="data",
+        )
+
+
+class TestCortexDBForgetFn(unittest.TestCase):
+    """Tests for the cortexdb_forget_fn factory."""
+
+    def setUp(self) -> None:
+        self.client = MagicMock()
+
+    def test_returns_callable(self) -> None:
+        fn = cortexdb_forget_fn(self.client)
+        self.assertTrue(callable(fn))
+
+    def test_function_name(self) -> None:
+        fn = cortexdb_forget_fn(self.client)
+        self.assertEqual(fn.__name__, "cortexdb_forget")
+
+    def test_calls_forget_with_reason(self) -> None:
+        fn = cortexdb_forget_fn(self.client, scope="user:t1")
+        result = fn(reason="outdated")
+        self.client.forget.assert_called_once_with(
+            "user:t1",
+            confirm_all=True,
+            cascade="redact_events",
+            reason="outdated",
+        )
+        self.assertIn("user:t1", result)
+        self.assertIn("forgotten", result)
+
+
+class TestRegisterCortexDBTools(unittest.TestCase):
+    """Tests for register_cortexdb_tools."""
+
+    def setUp(self) -> None:
+        self.client = MagicMock()
+        self.agent = MagicMock()
+        self.executor = MagicMock()
+        self.agent.register_for_llm.return_value = lambda fn: fn
+        self.executor.register_for_execution.return_value = lambda fn: fn
+
+    def test_registers_all_three_tools(self) -> None:
+        register_cortexdb_tools(self.agent, self.executor, self.client)
+        self.assertEqual(self.agent.register_for_llm.call_count, 3)
+        self.assertEqual(self.executor.register_for_execution.call_count, 3)
+
+    def test_descriptions_passed_to_agent(self) -> None:
+        register_cortexdb_tools(self.agent, self.executor, self.client)
+        descriptions = [
+            call.kwargs["description"]
+            for call in self.agent.register_for_llm.call_args_list
+        ]
+        self.assertTrue(any("Search" in d for d in descriptions))
+        self.assertTrue(any("Store" in d for d in descriptions))
+        self.assertTrue(any("Forget" in d for d in descriptions))
+
+
+if __name__ == "__main__":
+    unittest.main()