hipcortex 0.2.0__tar.gz

hipcortex-0.2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: hipcortex
+Version: 0.2.0
+Summary: Persistent causal memory for AI agents — LangChain, LlamaIndex, AutoGen, CrewAI
+Author: HipCortex Contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/farmountain/HipCortex
+Project-URL: Repository, https://github.com/farmountain/HipCortex
+Project-URL: Issues, https://github.com/farmountain/HipCortex/issues
+Project-URL: Benchmark, https://github.com/farmountain/HipCortex/blob/main/BENCHMARK.md
+Keywords: ai,memory,langchain,autogen,crewai,llm,agents,rag
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: httpx>=0.27
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28; extra == "crewai"
+Requires-Dist: crewai-tools>=0.1; extra == "crewai"
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2; extra == "autogen"
+Provides-Extra: benchmark
+Requires-Dist: mem0ai>=0.1; extra == "benchmark"
+Requires-Dist: tabulate>=0.9; extra == "benchmark"
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1; extra == "all"
+Requires-Dist: llama-index-core>=0.10; extra == "all"
+Requires-Dist: crewai>=0.28; extra == "all"
+Requires-Dist: crewai-tools>=0.1; extra == "all"
+Requires-Dist: pyautogen>=0.2; extra == "all"
+Requires-Dist: mem0ai>=0.1; extra == "all"
+Requires-Dist: tabulate>=0.9; extra == "all"
+Dynamic: requires-python
+
+# hipcortex
+
+**Persistent causal memory for AI agents — LangChain, LlamaIndex, AutoGen, CrewAI.**
+
+1.74ms p50 write latency. Temporal decay. Causal world model. Merkle-chained audit log. GDPR right-to-forget.
+
+## Install
+
+```bash
+pip install hipcortex
+```
+
+## Quick start
+
+```python
+from hipcortex import HipCortexClient
+
+client = HipCortexClient("http://localhost:3030")
+
+# Store memory
+client.add_memory(actor="alice", action="said", target="The meeting is at 3pm")
+
+# Search (keyword or cosine similarity)
+results = client.search("meeting time", limit=5)
+
+# Stats
+print(client.stats())
+
+# GDPR forget
+client.forget("alice")
+```
+
+## Framework integrations
+
+```python
+# LangChain — drop-in for ConversationBufferMemory
+from hipcortex.langchain_memory import HipCortexMemory
+memory = HipCortexMemory(session_id="user-42", url="http://localhost:3030")
+
+# LlamaIndex
+from hipcortex.llamaindex_storage import HipCortexChatStore
+store = HipCortexChatStore(client=client)
+
+# AutoGen
+from hipcortex.adapters.autogen import HipCortexAutoGenMemory
+mem = HipCortexAutoGenMemory(client=client, agent_id="researcher")
+agent.register_hook("process_message_before_send", mem.on_message_sent)
+
+# CrewAI
+from hipcortex.adapters.crewai import HipCortexRememberTool, HipCortexRecallTool
+tools = [HipCortexRememberTool(client=client), HipCortexRecallTool(client=client)]
+```
+
+## Start the server
+
+```bash
+# Self-hosted (single binary, zero deps)
+cargo run --bin webserver --no-default-features --features "web-server,petgraph_backend"
+
+# Fly.io
+fly deploy
+
+# Live demo
+https://hipcortex.fly.dev
+```
+
+**Full docs:** https://github.com/farmountain/HipCortex

hipcortex-0.2.0/README.md

@@ -0,0 +1,67 @@
+# hipcortex
+
+**Persistent causal memory for AI agents — LangChain, LlamaIndex, AutoGen, CrewAI.**
+
+1.74ms p50 write latency. Temporal decay. Causal world model. Merkle-chained audit log. GDPR right-to-forget.
+
+## Install
+
+```bash
+pip install hipcortex
+```
+
+## Quick start
+
+```python
+from hipcortex import HipCortexClient
+
+client = HipCortexClient("http://localhost:3030")
+
+# Store memory
+client.add_memory(actor="alice", action="said", target="The meeting is at 3pm")
+
+# Search (keyword or cosine similarity)
+results = client.search("meeting time", limit=5)
+
+# Stats
+print(client.stats())
+
+# GDPR forget
+client.forget("alice")
+```
+
+## Framework integrations
+
+```python
+# LangChain — drop-in for ConversationBufferMemory
+from hipcortex.langchain_memory import HipCortexMemory
+memory = HipCortexMemory(session_id="user-42", url="http://localhost:3030")
+
+# LlamaIndex
+from hipcortex.llamaindex_storage import HipCortexChatStore
+store = HipCortexChatStore(client=client)
+
+# AutoGen
+from hipcortex.adapters.autogen import HipCortexAutoGenMemory
+mem = HipCortexAutoGenMemory(client=client, agent_id="researcher")
+agent.register_hook("process_message_before_send", mem.on_message_sent)
+
+# CrewAI
+from hipcortex.adapters.crewai import HipCortexRememberTool, HipCortexRecallTool
+tools = [HipCortexRememberTool(client=client), HipCortexRecallTool(client=client)]
+```
+
+## Start the server
+
+```bash
+# Self-hosted (single binary, zero deps)
+cargo run --bin webserver --no-default-features --features "web-server,petgraph_backend"
+
+# Fly.io
+fly deploy
+
+# Live demo
+https://hipcortex.fly.dev
+```
+
+**Full docs:** https://github.com/farmountain/HipCortex

hipcortex-0.2.0/hipcortex/__init__.py

@@ -0,0 +1,15 @@
+"""HipCortex Python SDK — AI memory engine client."""
+
+from .client import HipCortexClient
+from .async_client import AsyncHipCortexClient
+from .langchain_memory import HipCortexMemory, AsyncHipCortexMemory
+from .llamaindex_storage import HipCortexStorageContext
+
+__version__ = "0.2.0"
+__all__ = [
+    "HipCortexClient",
+    "AsyncHipCortexClient",
+    "HipCortexMemory",
+    "AsyncHipCortexMemory",
+    "HipCortexStorageContext",
+]

hipcortex-0.2.0/hipcortex/adapters/__init__.py

@@ -0,0 +1 @@
+"""Framework adapters for HipCortex — AutoGen and CrewAI."""

hipcortex-0.2.0/hipcortex/adapters/autogen.py

@@ -0,0 +1,156 @@
+"""HipCortex AutoGen adapter — targets AutoGen 0.4+ (autogen-agentchat >= 0.4).
+
+AutoGen 0.4 changed from register_hook() to the Memory protocol.
+
+Usage (AutoGen 0.4+):
+    from autogen_agentchat.agents import AssistantAgent
+    from hipcortex import HipCortexClient
+    from hipcortex.adapters.autogen import HipCortexAutoGenMemory
+
+    client = HipCortexClient(base_url="http://localhost:3030")
+    memory = HipCortexAutoGenMemory(client=client, agent_id="researcher")
+    agent = AssistantAgent(name="researcher", model_client=..., memory=[memory])
+
+Usage (AutoGen 0.3 — legacy):
+    agent.register_hook("process_message_before_send", memory.on_message_sent_v03)
+    agent.register_hook("process_all_messages_before_reply", memory.on_messages_received_v03)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..client import HipCortexClient
+
+try:
+    from autogen_core.memory import Memory, MemoryContent, MemoryMimeType, MemoryQueryResult
+    from autogen_core import CancellationToken
+    _AUTOGEN4_AVAILABLE = True
+except ImportError:
+    _AUTOGEN4_AVAILABLE = False
+    class Memory:  # type: ignore[no-redef]
+        pass
+    class CancellationToken:  # type: ignore[no-redef]
+        pass
+
+
+class HipCortexAutoGenMemory(Memory):  # type: ignore[misc]
+    """AutoGen 0.4 Memory protocol backed by HipCortex."""
+
+    def __init__(
+        self,
+        client: HipCortexClient,
+        agent_id: str = "autogen-agent",
+        top_k: int = 10,
+    ) -> None:
+        self._client = client
+        self._agent_id = agent_id
+        self._top_k = top_k
+
+    # AutoGen 0.4 Memory protocol -------------------------------------------
+
+    async def add(
+        self,
+        content: Any,
+        cancellation_token: Optional[CancellationToken] = None,
+    ) -> None:
+        if _AUTOGEN4_AVAILABLE and hasattr(content, "content"):
+            text = str(content.content)
+            role = getattr(content, "role", None)
+            mime = getattr(content, "mime_type", None)
+            action = "ai_message" if (
+                (role and role in ("assistant", "ai")) or
+                (mime and "assistant" in str(mime).lower())
+            ) else "observation"
+        else:
+            text = str(content)
+            action = "observation"
+        self._client.add_memory(
+            actor=self._agent_id, action=action,
+            target=text, record_type="Temporal",
+        )
+
+    async def query(
+        self,
+        query: Any,
+        cancellation_token: Optional[CancellationToken] = None,
+    ) -> Any:
+        query_text = str(getattr(query, "content", query))
+        try:
+            search_results = self._client.search(query=query_text, limit=self._top_k)
+        except Exception:
+            search_results = [
+                {"record": r, "score": 1.0}
+                for r in self._client.get_conversation_history(self._agent_id, limit=self._top_k)
+            ]
+        if not _AUTOGEN4_AVAILABLE:
+            return search_results
+        memories = []
+        for item in search_results:
+            rec = item.get("record", item)
+            memories.append(MemoryContent(
+                content=rec.get("target", ""),
+                mime_type=MemoryMimeType.TEXT,
+                metadata={"score": item.get("score", 1.0), "actor": rec.get("actor", ""),
+                          "action": rec.get("action", ""), "timestamp": rec.get("timestamp", "")},
+            ))
+        return MemoryQueryResult(results=memories)
+
+    async def update_context(
+        self,
+        model_context: Any,
+        cancellation_token: Optional[CancellationToken] = None,
+    ) -> Any:
+        records = self._client.get_conversation_history(self._agent_id, limit=self._top_k)
+        records.sort(key=lambda r: r.get("timestamp", ""))
+        if not records:
+            return {"memories_added": 0}
+        lines = [f"[{r.get('action','memory')}] {r.get('target','')}" for r in records]
+        system_msg = {"role": "system", "content": "[HipCortex memory]\n" + "\n".join(lines)}
+        if hasattr(model_context, "add_message"):
+            await model_context.add_message(system_msg)
+        elif hasattr(model_context, "messages"):
+            model_context.messages.insert(0, system_msg)
+        return {"memories_added": len(records)}
+
+    async def clear(self) -> None:
+        self._client.forget(self._agent_id)
+
+    # AutoGen 0.3 legacy hooks -----------------------------------------------
+
+    def on_message_sent_v03(self, message: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]:
+        """AutoGen 0.3 hook: process_message_before_send."""
+        content = message.get("content", "")
+        role = message.get("role", "assistant")
+        action = "ai_message" if role == "assistant" else "human_message"
+        self._client.add_memory(actor=self._agent_id, action=action, target=str(content),
+                                record_type="Reflexion" if role == "assistant" else "Temporal")
+        return message
+
+    def on_messages_received_v03(
+        self, messages: List[Dict[str, Any]], **kwargs: Any
+    ) -> List[Dict[str, Any]]:
+        """AutoGen 0.3 hook: process_all_messages_before_reply."""
+        history = self._client.get_conversation_history(self._agent_id, limit=20)
+        if not history:
+            return messages
+        history.sort(key=lambda r: r.get("timestamp", ""))
+        lines = [
+            f"{'AI' if r.get('action') == 'ai_message' else 'Human'}: {r.get('target','')}"
+            for r in history
+        ]
+        return [{"role": "system", "content": "[HipCortex memory]\n" + "\n".join(lines)}] + list(messages)
+
+    # Sync helpers (no AutoGen needed) ---------------------------------------
+
+    def store(self, content: str, action: str = "observation") -> Dict[str, Any]:
+        return self._client.add_memory(actor=self._agent_id, action=action,
+                                       target=content, record_type="Temporal")
+
+    def recall(self, limit: int = 20) -> str:
+        records = self._client.get_conversation_history(self._agent_id, limit=limit)
+        records.sort(key=lambda r: r.get("timestamp", ""))
+        return "\n".join(f"[{r.get('action','?')}] {r.get('target','')}" for r in records)
+
+    def forget_all(self) -> Dict[str, Any]:
+        return self._client.forget(self._agent_id)

hipcortex-0.2.0/hipcortex/adapters/crewai.py

@@ -0,0 +1,153 @@
+"""CrewAI tool adapter for HipCortex.
+
+Exposes HipCortex memory operations as CrewAI ``BaseTool`` subclasses
+so agents can store and retrieve memories as tool calls during task execution.
+
+Usage::
+
+    from crewai import Agent, Task, Crew
+    from hipcortex import HipCortexClient
+    from hipcortex.adapters.crewai import (
+        HipCortexRememberTool,
+        HipCortexRecallTool,
+        HipCortexForgetTool,
+    )
+
+    client = HipCortexClient(base_url="http://localhost:3000")
+    tools = [
+        HipCortexRememberTool(client=client, agent_id="researcher"),
+        HipCortexRecallTool(client=client, agent_id="researcher"),
+        HipCortexForgetTool(client=client, agent_id="researcher"),
+    ]
+
+    researcher = Agent(
+        role="Senior Researcher",
+        goal="Research and remember findings",
+        tools=tools,
+        ...
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from ..client import HipCortexClient
+
+try:
+    from crewai_tools import BaseTool
+    from pydantic import BaseModel, Field
+    _CREWAI_AVAILABLE = True
+except ImportError:
+    _CREWAI_AVAILABLE = False
+
+    class BaseModel:  # type: ignore[no-redef]
+        pass
+
+    class Field:  # type: ignore[no-redef]
+        def __init__(self, *a: Any, **kw: Any) -> None: ...
+
+    class BaseTool:  # type: ignore[no-redef]
+        name: str = ""
+        description: str = ""
+        args_schema: Any = None
+        def _run(self, *a: Any, **kw: Any) -> str: ...
+
+
+# ---------------------------------------------------------------------------
+# Input schemas
+# ---------------------------------------------------------------------------
+
+if _CREWAI_AVAILABLE:
+    class RememberInput(BaseModel):
+        content: str = Field(..., description="Observation or fact to remember.")
+        action: str = Field(default="observation", description="Action tag (e.g. 'finding', 'decision').")
+
+    class RecallInput(BaseModel):
+        limit: int = Field(default=20, description="Max number of memories to return.")
+
+    class ForgetInput(BaseModel):
+        confirm: bool = Field(default=False, description="Set to True to confirm deletion.")
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+class HipCortexRememberTool(BaseTool):  # type: ignore[misc]
+    """CrewAI tool: store an observation in HipCortex memory."""
+
+    name: str = "hipcortex_remember"
+    description: str = (
+        "Store an important observation, finding, or decision in persistent memory. "
+        "Use this whenever you discover information worth remembering for future tasks."
+    )
+    if _CREWAI_AVAILABLE:
+        args_schema: Type[BaseModel] = RememberInput
+
+    def __init__(self, client: HipCortexClient, agent_id: str = "crewai-agent") -> None:
+        super().__init__()
+        self._client = client
+        self._agent_id = agent_id
+
+    def _run(self, content: str, action: str = "observation") -> str:
+        result = self._client.add_memory(
+            actor=self._agent_id,
+            action=action,
+            target=content,
+            record_type="Temporal",
+        )
+        if result.get("success"):
+            return f"Stored memory with id={result.get('record_id', '?')}"
+        return f"Failed to store memory: {result.get('error', 'unknown error')}"
+
+
+class HipCortexRecallTool(BaseTool):  # type: ignore[misc]
+    """CrewAI tool: retrieve recent memories from HipCortex."""
+
+    name: str = "hipcortex_recall"
+    description: str = (
+        "Retrieve recent memories and observations stored in HipCortex. "
+        "Use this to recall past findings before starting a new research task."
+    )
+    if _CREWAI_AVAILABLE:
+        args_schema: Type[BaseModel] = RecallInput
+
+    def __init__(self, client: HipCortexClient, agent_id: str = "crewai-agent") -> None:
+        super().__init__()
+        self._client = client
+        self._agent_id = agent_id
+
+    def _run(self, limit: int = 20) -> str:
+        records = self._client.get_conversation_history(self._agent_id, limit=limit)
+        if not records:
+            return "No memories found."
+        records.sort(key=lambda r: r.get("timestamp", ""))
+        lines = []
+        for i, rec in enumerate(records, 1):
+            lines.append(f"{i}. [{rec.get('action', '?')}] {rec.get('target', '')}")
+        return "\n".join(lines)
+
+
+class HipCortexForgetTool(BaseTool):  # type: ignore[misc]
+    """CrewAI tool: delete all memories for this agent (GDPR / session reset)."""
+
+    name: str = "hipcortex_forget"
+    description: str = (
+        "Delete all memories stored for this agent. "
+        "Only use this when explicitly asked to clear memory or start fresh."
+    )
+    if _CREWAI_AVAILABLE:
+        args_schema: Type[BaseModel] = ForgetInput
+
+    def __init__(self, client: HipCortexClient, agent_id: str = "crewai-agent") -> None:
+        super().__init__()
+        self._client = client
+        self._agent_id = agent_id
+
+    def _run(self, confirm: bool = False) -> str:
+        if not confirm:
+            return "Deletion not confirmed. Pass confirm=True to proceed."
+        result = self._client.forget(self._agent_id)
+        deleted = result.get("records_deleted", 0)
+        return f"Deleted {deleted} memory records for agent '{self._agent_id}'."