uams-sdk 1.0.1__tar.gz

uams_sdk-1.0.1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: uams-sdk
+Version: 1.0.1
+Summary: Shared Memory SDK for Hermes and OpenClaw targeting the Unified Agent Memory System.
+Author: Shivam Sharma
+Project-URL: Homepage, https://github.com/Shivamsharma6/unified_memory
+Project-URL: Repository, https://github.com/Shivamsharma6/unified_memory.git
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: mcp[cli]<1.13,>=1.12.4
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"

uams_sdk-1.0.1/README.md

@@ -0,0 +1,93 @@
+# UAMS Shared Memory SDK
+
+A unified, asynchronous Python SDK for the **Unified Agent Memory System (UAMS)**. 
+Designed to be shared natively by both **Hermes** and **OpenClaw** agents.
+
+## Features
+- **Unified Client:** One standard interface for all agents.
+- **Async First:** Built on `httpx` for non-blocking operations.
+- **Intelligent Caching:** Built-in TTL caching with automatic invalidation on writes.
+- **Full API Coverage:** Semantic search, graph traversal, context compression, and writes.
+- **MCP Adapter:** Exposes UAMS as standard MCP tools, resources, and prompts for agent tool discovery.
+
+## Installation
+```bash
+pip install -e .
+```
+
+## Usage
+```python
+import asyncio
+from uams_sdk import UAMSClient
+
+async def main():
+    client = UAMSClient(base_url="http://localhost:8000")
+    task = "How do I fix Docker file locks?"
+
+    # Default preflight before the agent works.
+    memory = await client.begin_task(task)
+    print(memory["context"])
+
+    # Default write-back after durable work.
+    await client.end_task(
+        task=task,
+        outcome="Documented the Docker file-lock workaround.",
+        entities=["Docker File Locks"],
+        tags=["#procedure"],
+    )
+
+asyncio.run(main())
+```
+
+## MCP Server
+
+Run the adapter from the repository root:
+
+```bash
+./uams mcp
+```
+
+Or run the installed console entry point:
+
+```bash
+UAMS_API_URL=http://localhost:8000 uams-mcp
+```
+
+Agent MCP config:
+
+```json
+{
+  "mcpServers": {
+    "uams": {
+      "command": "/absolute/path/to/unified_memory/uams",
+      "args": ["mcp"],
+      "env": {
+        "UAMS_API_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+Generate snippets from the repository root:
+
+```bash
+./uams mcp-config all
+./uams mcp-config codex
+./uams mcp-config json
+```
+
+Discovered MCP capabilities:
+
+- Tools: `begin_task`, `end_task`, `health`, `search_memory`, `get_context`, `get_procedures`, `remember`, `get_related_entities`, `summarize_memory`, `store_fix_summary`
+- Resource: `uams://memory-policy`
+- Prompt: `use_uams_memory`
+
+Agent default protocol:
+
+```text
+Before each non-trivial task, call `begin_task`.
+During work, call `search_memory` when more recall is needed.
+After durable work, call `end_task`.
+Never store raw transcripts; store distilled facts, decisions, fixes, and procedures.
+```

uams_sdk-1.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uams-sdk"
+version = "1.0.1"
+description = "Shared Memory SDK for Hermes and OpenClaw targeting the Unified Agent Memory System."
+authors = [{ name = "Shivam Sharma" }]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "cachetools>=5.3.0",
+    "mcp[cli]>=1.12.4,<1.13"
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence"
+]
+
+[project.urls]
+Homepage = "https://github.com/Shivamsharma6/unified_memory"
+Repository = "https://github.com/Shivamsharma6/unified_memory.git"
+
+[project.scripts]
+uams-mcp = "uams_sdk.mcp_server:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio"
+]

uams_sdk-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uams_sdk-1.0.1/tests/test_mcp_identity.py

@@ -0,0 +1,30 @@
+import pytest
+from uams_sdk.mcp_server import mcp
+
+
+@pytest.mark.asyncio
+async def test_get_identity_tool_exists():
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+    assert "get_identity" in tool_names
+
+
+@pytest.mark.asyncio
+async def test_inject_identity_tool_exists():
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+    assert "inject_identity" in tool_names
+
+
+@pytest.mark.asyncio
+async def test_extract_identity_tool_exists():
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+    assert "extract_identity" in tool_names
+
+
+@pytest.mark.asyncio
+async def test_memory_quality_tool_exists():
+    tools = await mcp.list_tools()
+    tool_names = [t.name for t in tools]
+    assert "memory_quality" in tool_names

uams_sdk-1.0.1/uams_sdk/__init__.py

@@ -0,0 +1,5 @@
+from .client import UAMSClient
+from .exceptions import UAMSError, UAMSConnectionError, UAMSAPIError
+from .middleware import AutonomousMemoryMiddleware
+
+__all__ = ["UAMSClient", "UAMSError", "UAMSConnectionError", "UAMSAPIError", "AutonomousMemoryMiddleware"]

uams_sdk-1.0.1/uams_sdk/cache.py

@@ -0,0 +1,24 @@
+from cachetools import TTLCache
+import hashlib
+import json
+from typing import Any, Dict
+
+class SDKCache:
+    """In-memory TTL cache for SDK requests to reduce API load."""
+    def __init__(self, maxsize: int = 1000, ttl: int = 300):
+        self.cache = TTLCache(maxsize=maxsize, ttl=ttl)
+        
+    def _generate_key(self, endpoint: str, params: Dict[str, Any]) -> str:
+        param_str = json.dumps(params, sort_keys=True)
+        return hashlib.md5(f"{endpoint}:{param_str}".encode()).hexdigest()
+        
+    def get(self, endpoint: str, params: Dict[str, Any]) -> Any:
+        key = self._generate_key(endpoint, params)
+        return self.cache.get(key)
+        
+    def set(self, endpoint: str, params: Dict[str, Any], data: Any):
+        key = self._generate_key(endpoint, params)
+        self.cache[key] = data
+        
+    def clear(self):
+        self.cache.clear()

uams_sdk-1.0.1/uams_sdk/client.py

@@ -0,0 +1,183 @@
+import httpx
+import logging
+import json
+from datetime import date
+from typing import Dict, Any, List, Optional
+from .cache import SDKCache
+from .exceptions import UAMSError, UAMSConnectionError, UAMSAPIError
+
+logger = logging.getLogger(__name__)
+
+class UAMSClient:
+    """
+    Unified Agent Memory System (UAMS) SDK Client.
+    Shared across Hermes, OpenClaw, and VoiceAI.
+    """
+    def __init__(self, base_url: str = "http://localhost:8000", cache_ttl: int = 300):
+        self.base_url = base_url
+        self.timeout = httpx.Timeout(15.0, connect=5.0)
+        self.cache = SDKCache(ttl=cache_ttl)
+
+    async def _request(self, method: str, endpoint: str, json_data: Dict[str, Any] = None, use_cache: bool = False) -> Dict[str, Any]:
+        if use_cache and method == "POST":
+            cached = self.cache.get(endpoint, json_data or {})
+            if cached:
+                logger.debug(f"Cache hit for {endpoint}")
+                return cached
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            try:
+                if method == "POST":
+                    response = await client.post(f"{self.base_url}{endpoint}", json=json_data or {})
+                elif method == "GET":
+                    response = await client.get(f"{self.base_url}{endpoint}", params=json_data)
+                else:
+                    raise ValueError(f"Unsupported method: {method}")
+                    
+                response.raise_for_status()
+                data = response.json()
+                
+                if use_cache and method == "POST":
+                    self.cache.set(endpoint, json_data or {}, data)
+                    
+                return data
+                
+            except httpx.HTTPStatusError as e:
+                raise UAMSAPIError(f"API Error: {e.response.status_code}", status_code=e.response.status_code, details=e.response.text)
+            except httpx.RequestError as e:
+                raise UAMSConnectionError(f"Connection error to UAMS {endpoint}: {str(e)}")
+
+    async def search(self, query: str, limit: int = 5, entities: List[str] = None, compress: bool = True) -> Dict[str, Any]:
+        """Semantic + Graph hybrid retrieval."""
+        payload = {
+            "query": query,
+            "limit": limit,
+            "entities": entities or [],
+            "compress": compress
+        }
+        return await self._request("POST", "/search", payload, use_cache=True)
+
+    async def retrieve_context(self, task: str, max_tokens: int = 2000) -> str:
+        """Highly compressed context assembly for LLM prompting."""
+        res = await self._request("POST", "/context", {"task": task, "max_tokens": max_tokens}, use_cache=True)
+        return res.get("context", "")
+
+    async def retrieve_procedures(self, task: str) -> List[str]:
+        """Fetch procedural memories (AGENTS.md / SOPs)."""
+        res = await self._request("POST", f"/procedures", {"task": task}, use_cache=True)
+        return res.get("procedures", [])
+
+    async def begin_task(self, task: str, max_tokens: int = 2000) -> Dict[str, Any]:
+        """Default memory preflight agents should call before doing work."""
+        procedures = await self.retrieve_procedures(task)
+        context = await self.retrieve_context(task, max_tokens=max_tokens)
+        return {
+            "task": task,
+            "status": "ready",
+            "procedures": procedures,
+            "context": context,
+            "max_tokens": max_tokens,
+            "memory_policy": (
+                "Always call begin_task before non-trivial work. Use the procedures and "
+                "context as grounding. Call search_memory when recall is needed during "
+                "the task. Call end_task after durable work to store distilled outcomes."
+            ),
+        }
+
+    async def store_memory(self, text: str, category: str = "episodic", tags: List[str] = None) -> bool:
+        """Agent memory write support. Clears cache to ensure fresh reads."""
+        payload = {"text": text, "category": category, "tags": tags or []}
+        try:
+            await self._request("POST", "/remember", payload, use_cache=False)
+            self.cache.clear() # Invalidate cache on write
+            return True
+        except UAMSError as e:
+            logger.error(f"Failed to store memory: {e}")
+            return False
+
+    async def end_task(
+        self,
+        task: str,
+        outcome: str,
+        files: Optional[List[str]] = None,
+        decisions: Optional[List[str]] = None,
+        fixes: Optional[List[str]] = None,
+        entities: Optional[List[str]] = None,
+        tags: Optional[List[str]] = None,
+        category: str = "episodic",
+    ) -> Dict[str, Any]:
+        """Store a distilled task outcome after durable work completes."""
+        all_tags = list(dict.fromkeys((tags or []) + ["#auto-distilled", "#task-outcome"]))
+        entity_links = " ".join(f"[[{entity}]]" for entity in entities or [])
+        file_lines = "\n".join(f"- `{path}`" for path in files or []) or "- Not specified"
+        decision_lines = "\n".join(f"- {item}" for item in decisions or []) or "- None recorded"
+        fix_lines = "\n".join(f"- {item}" for item in fixes or []) or "- None recorded"
+        today = date.today().isoformat()
+
+        tags_json = json.dumps(all_tags)
+        text = f"""---
+type: {category}
+date: {today}
+tags: {tags_json}
+---
+# Task Outcome: {task}
+
+## TL;DR
+{outcome.strip()}
+
+## Entities
+{entity_links or f"[[{task}]]"}
+
+## Files
+{file_lines}
+
+## Decisions
+{decision_lines}
+
+## Fixes
+{fix_lines}
+
+## Retrieval Notes
+Future agents should search for [[{task}]], the listed entities, and the listed files before repeating related work.
+"""
+        ok = await self.store_memory(text=text, category=category, tags=all_tags)
+        return {"ok": ok, "category": category, "tags": all_tags}
+
+    async def distill_memory(self, topic: str) -> str:
+        """Trigger summarization/distillation of a topic."""
+        res = await self._request("POST", "/summarize", {"topic": topic}, use_cache=False)
+        return res.get("summary", "")
+
+    async def related_entities(self, entity: str, radius: int = 1) -> Dict[str, Any]:
+        """Graph retrieval: neighborhood expansion."""
+        try:
+            return await self._request("GET", f"/graph/neighborhood/{entity}", {"radius": radius}, use_cache=True)
+        except UAMSAPIError as e:
+            if getattr(e, 'status_code', None) == 404:
+                return {"error": f"Entity '{entity}' not found in knowledge graph.", "nodes": [], "links": []}
+            raise
+
+    async def get_identity(self, entity_id: str = "default") -> Dict[str, Any]:
+        """Get identity profile."""
+        return await self._request("POST", "/identity/profile", {"entity_id": entity_id}, use_cache=True)
+
+    async def inject_identity(
+        self, entity_id: str = "default", query: str = "", task_type: str = "general"
+    ) -> Dict[str, Any]:
+        """Inject identity into reasoning."""
+        return await self._request("POST", "/identity/inject", {
+            "entity_id": entity_id, "query": query, "task_type": task_type
+        }, use_cache=False)
+
+    async def extract_identity(
+        self, entity_id: str = "default", entity_name: str = "Agent",
+        memories: Optional[List[Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        """Extract identity from memories."""
+        return await self._request("POST", "/identity/extract", {
+            "entity_id": entity_id, "entity_name": entity_name, "memories": memories or []
+        }, use_cache=False)
+
+    async def memory_quality(self, path: str) -> Dict[str, Any]:
+        """Score memory quality."""
+        return await self._request("POST", "/memory/quality", {"path": path}, use_cache=True)

uams_sdk-1.0.1/uams_sdk/exceptions.py

@@ -0,0 +1,14 @@
+class UAMSError(Exception):
+    """Base exception for UAMS SDK."""
+    pass
+
+class UAMSConnectionError(UAMSError):
+    """Raised when the API is unreachable."""
+    pass
+
+class UAMSAPIError(UAMSError):
+    """Raised when the API returns an error response."""
+    def __init__(self, message: str, status_code: int = None, details: str = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.details = details

uams_sdk-1.0.1/uams_sdk/mcp_server.py

@@ -0,0 +1,249 @@
+import os
+from datetime import date
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import UAMSClient
+
+
+DEFAULT_BASE_URL = os.getenv("UAMS_API_URL", "http://localhost:8000")
+
+mcp = FastMCP(
+    "Unified Agent Memory",
+    instructions=(
+        "Use UAMS as the default shared memory backend. Before coding or answering, "
+        "call begin_task for relevant procedures and context. After durable work, "
+        "call end_task with distilled, non-transcript outcomes. Use search_memory "
+        "during work when additional recall is needed."
+    ),
+)
+
+
+def _client() -> UAMSClient:
+    return UAMSClient(base_url=os.getenv("UAMS_API_URL", DEFAULT_BASE_URL))
+
+
+@mcp.resource("uams://memory-policy")
+def memory_policy() -> str:
+    """Default operating policy agents should follow when UAMS is available."""
+    return """# UAMS Default Memory Policy
+
+Before each task:
+- Call `begin_task` for task-specific rules, compressed historical context, and graph context.
+- Use `search_memory` when targeted lookup is needed.
+
+After each task:
+- Call `end_task` with distilled outcomes.
+- Store only durable facts, decisions, fixes, and procedures.
+- Never store raw chat transcripts.
+- Prefer wikilinks like `[[Entity Name]]` and tags like `#bugfix`.
+- Use `store_fix_summary` for bug fixes so future retrieval can explain cause and resolution.
+"""
+
+
+@mcp.prompt(title="Use UAMS Memory")
+def use_uams_memory(task: str) -> str:
+    """Prompt template that makes an agent default to UAMS for a task."""
+    return f"""You have access to Unified Agent Memory System tools.
+
+Task: {task}
+
+Protocol:
+1. Call `begin_task` with the task.
+2. Use the returned procedures and context as grounding before acting.
+3. Use `search_memory` during work when additional recall is needed.
+4. After completing durable work, call `end_task`.
+5. Store distilled atomic memory only, never raw conversation."""
+
+
+@mcp.tool()
+async def health() -> dict[str, Any]:
+    """Check whether the UAMS Retrieval API is reachable."""
+    return await _client()._request("GET", "/health", use_cache=False)
+
+
+@mcp.tool()
+async def search_memory(
+    query: str,
+    limit: int = 5,
+    entities: list[str] | None = None,
+    compress: bool = True,
+) -> dict[str, Any]:
+    """Search UAMS using hybrid semantic and graph-aware retrieval."""
+    return await _client().search(
+        query=query,
+        limit=limit,
+        entities=entities or [],
+        compress=compress,
+    )
+
+
+@mcp.tool()
+async def begin_task(task: str, max_tokens: int = 2000) -> dict[str, Any]:
+    """Default first call before work: retrieve procedures, context, and memory policy."""
+    return await _client().begin_task(task=task, max_tokens=max_tokens)
+
+
+@mcp.tool()
+async def get_context(task: str, max_tokens: int = 2000) -> dict[str, Any]:
+    """Return compressed memory context for an agent task."""
+    context = await _client().retrieve_context(task=task, max_tokens=max_tokens)
+    return {"task": task, "context": context, "max_tokens": max_tokens}
+
+
+@mcp.tool()
+async def get_procedures(task: str) -> dict[str, Any]:
+    """Return procedural memories and operating rules relevant to a task."""
+    procedures = await _client().retrieve_procedures(task=task)
+    return {"task": task, "procedures": procedures}
+
+
+@mcp.tool()
+async def remember(
+    text: str,
+    category: str = "episodic",
+    tags: list[str] | None = None,
+) -> dict[str, Any]:
+    """Store a distilled memory in UAMS. Do not use for raw transcripts."""
+    ok = await _client().store_memory(
+        text=text,
+        category=category,
+        tags=tags or [],
+    )
+    return {"ok": ok, "category": category, "tags": tags or []}
+
+
+@mcp.tool()
+async def end_task(
+    task: str,
+    outcome: str,
+    files: list[str] | None = None,
+    decisions: list[str] | None = None,
+    fixes: list[str] | None = None,
+    entities: list[str] | None = None,
+    tags: list[str] | None = None,
+    category: str = "episodic",
+) -> dict[str, Any]:
+    """Default final call after durable work: store distilled task outcome memory."""
+    return await _client().end_task(
+        task=task,
+        outcome=outcome,
+        files=files or [],
+        decisions=decisions or [],
+        fixes=fixes or [],
+        entities=entities or [],
+        tags=tags or [],
+        category=category,
+    )
+
+
+@mcp.tool()
+async def get_related_entities(entity: str, radius: int = 1) -> dict[str, Any]:
+    """Fetch a graph neighborhood around an entity."""
+    return await _client().related_entities(entity=entity, radius=radius)
+
+
+@mcp.tool()
+async def summarize_memory(topic: str) -> dict[str, Any]:
+    """Ask UAMS to generate or retrieve a semantic summary for a topic."""
+    summary = await _client().distill_memory(topic=topic)
+    return {"topic": topic, "summary": summary}
+
+
+@mcp.tool()
+async def store_fix_summary(
+    issue: str,
+    cause: str,
+    resolution: str,
+    files: list[str] | None = None,
+    entities: list[str] | None = None,
+    tags: list[str] | None = None,
+) -> dict[str, Any]:
+    """Store a durable bug-fix memory with cause, resolution, files, and entities."""
+    all_tags = list(dict.fromkeys((tags or []) + ["#bugfix", "#auto-distilled"]))
+    linked_entities = " ".join(f"[[{entity}]]" for entity in entities or [])
+    file_list = "\n".join(f"- `{path}`" for path in files or [])
+    today = date.today().isoformat()
+
+    import json
+    tags_json = json.dumps(all_tags)
+    text = f"""---
+type: procedural
+date: {today}
+tags: {tags_json}
+---
+# Fix Summary: {issue}
+
+## TL;DR
+[[{issue}]] was caused by {cause} and resolved by {resolution}.
+
+## Entities
+{linked_entities or f"[[{issue}]]"}
+
+## Files
+{file_list or "- Not specified"}
+
+## Cause
+{cause}
+
+## Resolution
+{resolution}
+
+## Retrieval Notes
+Future agents should search for [[{issue}]], related files, and the listed entities before re-debugging this class of issue.
+"""
+
+    ok = await _client().store_memory(text=text, category="procedural", tags=all_tags)
+    return {
+        "ok": ok,
+        "issue": issue,
+        "category": "procedural",
+        "tags": all_tags,
+    }
+
+
+@mcp.tool()
+async def get_identity(entity_id: str = "default") -> dict[str, Any]:
+    """Get the identity profile for an entity (traits, confidence, version)."""
+    return await _client().get_identity(entity_id=entity_id)
+
+
+@mcp.tool()
+async def inject_identity(
+    entity_id: str = "default",
+    query: str = "",
+    task_type: str = "general",
+) -> dict[str, Any]:
+    """Inject identity context into agent reasoning for personalized responses."""
+    return await _client().inject_identity(
+        entity_id=entity_id, query=query, task_type=task_type
+    )
+
+
+@mcp.tool()
+async def extract_identity(
+    entity_id: str = "default",
+    entity_name: str = "Agent",
+    memories: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Extract identity traits from episodic memories."""
+    return await _client().extract_identity(
+        entity_id=entity_id,
+        entity_name=entity_name,
+        memories=memories or [],
+    )
+
+
+@mcp.tool()
+async def memory_quality(path: str) -> dict[str, Any]:
+    """Score a memory note's quality and completeness."""
+    return await _client().memory_quality(path=path)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

uams_sdk-1.0.1/uams_sdk/middleware.py

@@ -0,0 +1,114 @@
+import logging
+import re
+from typing import Dict, Any, List, Optional
+from .client import UAMSClient
+
+logger = logging.getLogger(__name__)
+
+class AutonomousMemoryMiddleware:
+    """
+    Advanced Automatic Memory Middleware for Hermes & OpenClaw.
+    Automatically orchestrates memory injection before tasks and knowledge extraction after tasks.
+    """
+    def __init__(self, client: Optional[UAMSClient] = None):
+        self.client = client or UAMSClient()
+        self.max_context_tokens = 2000
+
+    def _detect_task_type(self, prompt: str) -> str:
+        """1. Detect task type via heuristic."""
+        q = prompt.lower()
+        if any(w in q for w in ["code", "script", "debug", "error", "refactor", "build"]):
+            return "coding"
+        if any(w in q for w in ["explain", "research", "what is", "why", "how does"]):
+            return "research"
+        return "general"
+
+    async def pre_task(self, user_prompt: str) -> str:
+        """
+        Executed BEFORE the agent sees the prompt.
+        1. Detect task type
+        2. Retrieve procedures first
+        3. Retrieve relevant memory automatically
+        4. Compress context
+        5. Inject memory into prompt
+        """
+        task_type = self._detect_task_type(user_prompt)
+        logger.info(f"[UAMS Middleware] Task detected as '{task_type}'. Fetching memory...")
+
+        memory_packet = await self.client.begin_task(
+            task=user_prompt,
+            max_tokens=self.max_context_tokens,
+        )
+        procedures = memory_packet.get("procedures", [])
+        proc_text = "\n".join(procedures) if procedures else "No specific operating procedures found."
+        context = memory_packet.get("context", "")
+        context_text = context if context else "No historical context found."
+
+        # 5. Inject memory into prompt
+        augmented_prompt = f"""<uams_context>
+[System] Task Type: {task_type.capitalize()}
+
+[Operating Procedures]
+{proc_text}
+
+[Historical Memory & Graph Context]
+{context_text}
+</uams_context>
+
+User Request: {user_prompt}"""
+
+        return augmented_prompt
+
+    def _extract_insights(self, response: str) -> List[Dict[str, Any]]:
+        """
+        Heuristic to extract durable knowledge from the agent's response.
+        In production, this could be a lightweight LLM call.
+        """
+        insights = []
+        
+        # Look for explicit decisions, fixes, or procedures in the text
+        fix_match = re.search(r'(?i)(?:I fixed this by|The solution was|Resolution:)(.*?)(?:\n\n|$)', response, re.DOTALL)
+        if fix_match:
+            insights.append({"text": f"Fix applied: {fix_match.group(1).strip()}", "category": "procedural"})
+            
+        decision_match = re.search(r'(?i)(?:I have decided to|Decision:)(.*?)(?:\n\n|$)', response, re.DOTALL)
+        if decision_match:
+            insights.append({"text": f"Decision made: {decision_match.group(1).strip()}", "category": "semantic"})
+
+        # Fallback to episodic if we just completed a significant task successfully
+        if not insights and ("successfully" in response.lower() or "completed" in response.lower()):
+            # We'll just take the first sentence as an episodic summary
+            first_sentence = response.split('.')[0] + "."
+            insights.append({"text": f"Task completed: {first_sentence}", "category": "episodic"})
+
+        return insights
+
+    async def post_task(self, user_prompt: str, agent_response: str) -> None:
+        """
+        Executed AFTER the agent finishes the task.
+        1. Determine if durable knowledge was generated
+        2. Distill reusable insights
+        3. Store procedural memory
+        4. Update graph relationships (Triggered by the store endpoint internally)
+        """
+        logger.info("[UAMS Middleware] Evaluating task output for durable knowledge...")
+        
+        insights = self._extract_insights(agent_response)
+        
+        if not insights:
+            logger.debug("[UAMS Middleware] No durable knowledge detected in response.")
+            return
+
+        for insight in insights:
+            logger.info(f"[UAMS Middleware] Distilled Insight ({insight['category']}): {insight['text'][:50]}...")
+            
+            # 3 & 4. Store memory and update relationships
+            # The UAMS watcher handles graph relationship updates upon file creation
+            await self.client.end_task(
+                task=user_prompt,
+                outcome=insight["text"],
+                tags=[f"#{self._detect_task_type(user_prompt)}"],
+                category=insight["category"],
+            )
+            
+        logger.info("[UAMS Middleware] Knowledge successfully synchronized to the Unified Memory System.")

uams_sdk-1.0.1/uams_sdk.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: uams-sdk
+Version: 1.0.1
+Summary: Shared Memory SDK for Hermes and OpenClaw targeting the Unified Agent Memory System.
+Author: Shivam Sharma
+Project-URL: Homepage, https://github.com/Shivamsharma6/unified_memory
+Project-URL: Repository, https://github.com/Shivamsharma6/unified_memory.git
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: mcp[cli]<1.13,>=1.12.4
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"

uams_sdk-1.0.1/uams_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+tests/test_mcp_identity.py
+uams_sdk/__init__.py
+uams_sdk/cache.py
+uams_sdk/client.py
+uams_sdk/exceptions.py
+uams_sdk/mcp_server.py
+uams_sdk/middleware.py
+uams_sdk.egg-info/PKG-INFO
+uams_sdk.egg-info/SOURCES.txt
+uams_sdk.egg-info/dependency_links.txt
+uams_sdk.egg-info/entry_points.txt
+uams_sdk.egg-info/requires.txt
+uams_sdk.egg-info/top_level.txt

uams_sdk-1.0.1/uams_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

uams_sdk-1.0.1/uams_sdk.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+uams-mcp = uams_sdk.mcp_server:main

uams_sdk-1.0.1/uams_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+httpx>=0.27.0
+pydantic>=2.0.0
+cachetools>=5.3.0
+mcp[cli]<1.13,>=1.12.4
+
+[dev]
+pytest
+pytest-asyncio

uams_sdk-1.0.1/uams_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+uams_sdk