Merge pull request #68 from redis/docs/restructure-memory-documentation

This PR includes a few changes: a new feature, a performance fix, a bug fix, and docs enhancements.

New feature: Reconstruct working memory messages from long-term storage
If you turn on the index_all_messages_in_long_term_memory setting (off by default), the server will copy all messages found in working memory sessions to long-term storage. Later, if a client requests a working memory session by ID, and the server does not find one (because it's expired or you deleted it), the server will try to reconstruct the session from long-term storage by searching for messages with that session ID. This allows you to set a TTL on working memory and expire it quickly, but retain the ability to restore the session from working memory if a user resumes the session later.

NOTE: This setting requires some care, so it's disabled by default. You most likely want to set TTLs on working memory if you use this feature. Also, if you use long-term search without specifying memory types, you may get duplicates of the same information (one from a message, one from episodic or semantic memory).

Bug fix: calculating remaining context works better now
There was a bug in how we calculated remaining context after updating a working memory session.

Defaults change: Turn off query optimization by default
Long-term search was optimizing all queries by default. This introduces latency and is mostly useful if you're searching directly with user queries, which most agents won't do (instead, an LLM will search through function calls).

Docs: Restructures the documentation to provide a cleaner, more logical organization.

Author: abrookins

.github/workflows/python-tests.yml

@@ -65,49 +65,3 @@ jobs:
         uv run pytest --run-api-tests
       env:
         OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-
-  docker:
-    needs: test
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-    steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v3
-
-    - name: Log in to Docker Hub
-      uses: docker/login-action@v3
-      with:
-        username: ${{ secrets.DOCKER_USERNAME }}
-        password: ${{ secrets.DOCKER_TOKEN }}
-
-    - name: Log in to GitHub Container Registry
-      uses: docker/login-action@v3
-      with:
-        registry: ghcr.io
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Extract version from __init__.py
-      id: version
-      run: |
-        VERSION=$(grep '__version__ =' agent_memory_server/__init__.py | sed 's/__version__ = "\(.*\)"/\1/' || echo "latest")
-        echo "version=$VERSION" >> $GITHUB_OUTPUT
-        echo "Version: $VERSION"
-
-    - name: Build and push Docker image
-      uses: docker/build-push-action@v5
-      with:
-        context: .
-        file: ./Dockerfile
-        platforms: linux/amd64,linux/arm64
-        push: true
-        tags: |
-          redislabs/agent-memory-server:latest
-          redislabs/agent-memory-server:${{ steps.version.outputs.version }}
-          ghcr.io/${{ github.repository }}:latest
-          ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}
-        cache-from: type=gha
-        cache-to: type=gha,mode=max

.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Release Docker Images
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (leave empty to use version from __init__.py)'
+        required: false
+        type: string
+      push_latest:
+        description: 'Also tag as latest'
+        required: true
+        type: boolean
+        default: true
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Docker Hub
+      uses: docker/login-action@v3
+      with:
+        username: ${{ secrets.DOCKER_USERNAME }}
+        password: ${{ secrets.DOCKER_TOKEN }}
+
+    - name: Log in to GitHub Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Determine version
+      id: version
+      run: |
+        if [ -n "${{ inputs.version }}" ]; then
+          VERSION="${{ inputs.version }}"
+        else
+          VERSION=$(grep '__version__ =' agent_memory_server/__init__.py | sed 's/__version__ = "\(.*\)"/\1/' || echo "latest")
+        fi
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "Version to release: $VERSION"
+
+    - name: Build tags list
+      id: tags
+      run: |
+        TAGS="redislabs/agent-memory-server:${{ steps.version.outputs.version }}"
+        TAGS="$TAGS,ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}"
+
+        if [ "${{ inputs.push_latest }}" = "true" ]; then
+          TAGS="$TAGS,redislabs/agent-memory-server:latest"
+          TAGS="$TAGS,ghcr.io/${{ github.repository }}:latest"
+        fi
+
+        echo "tags=$TAGS" >> $GITHUB_OUTPUT
+        echo "Tags to push: $TAGS"
+
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        file: ./Dockerfile
+        platforms: linux/amd64,linux/arm64
+        push: true
+        tags: ${{ steps.tags.outputs.tags }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+    - name: Create GitHub Release
+      uses: actions/create-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: v${{ steps.version.outputs.version }}
+        release_name: Release v${{ steps.version.outputs.version }}
+        body: |
+          Docker images published:
+          - `redislabs/agent-memory-server:${{ steps.version.outputs.version }}`
+          - `ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}`
+          ${{ inputs.push_latest && format('- `redislabs/agent-memory-server:latest`{0}- `ghcr.io/{1}:latest`', '\n          ', github.repository) || '' }}
+        draft: false
+        prerelease: false

agent-memory-client/README.md

@@ -100,6 +100,7 @@ working_memory = WorkingMemory(
     messages=[
         MemoryMessage(role="user", content="Hello!"),
         MemoryMessage(role="assistant", content="Hi there! How can I help?")
+        # created_at timestamps are automatically set for proper chronological ordering
     ],
     namespace="chat-app"
 )

agent-memory-client/agent_memory_client/__init__.py

@@ -5,7 +5,7 @@
 memory management capabilities for AI agents and applications.
 """
 
-__version__ = "0.12.1"
+__version__ = "0.12.2"
 
 from .client import MemoryAPIClient, MemoryClientConfig, create_memory_client
 from .exceptions import (

agent-memory-client/agent_memory_client/client.py

@@ -17,7 +17,12 @@
 from pydantic import BaseModel
 from ulid import ULID
 
-from .exceptions import MemoryClientError, MemoryServerError, MemoryValidationError
+from .exceptions import (
+    MemoryClientError,
+    MemoryNotFoundError,
+    MemoryServerError,
+    MemoryValidationError,
+)
 from .filters import (
     CreatedAt,
     Entities,
@@ -364,8 +369,15 @@ async def get_or_create_working_memory(
                 return (True, created_memory)
 
             return (False, existing_memory)
-        except httpx.HTTPStatusError as e:
-            if e.response.status_code == 404:
+        except (httpx.HTTPStatusError, MemoryNotFoundError) as e:
+            # Handle both HTTPStatusError and MemoryNotFoundError for 404s
+            is_404 = False
+            if isinstance(e, httpx.HTTPStatusError):
+                is_404 = e.response.status_code == 404
+            elif isinstance(e, MemoryNotFoundError):
+                is_404 = True
+
+            if is_404:
                 # Session doesn't exist, create it
                 empty_memory = WorkingMemory(
                     session_id=session_id,
@@ -885,14 +897,6 @@ async def search_long_term_memory(
             )
             response.raise_for_status()
             data = response.json()
-            # Some tests may stub json() as an async function; handle awaitable
-            try:
-                import inspect
-
-                if inspect.isawaitable(data):
-                    data = await data
-            except Exception:
-                pass
             return MemoryRecordResults(**data)
         except httpx.HTTPStatusError as e:
             self._handle_http_error(e.response)
@@ -1477,8 +1481,8 @@ def get_add_memory_tool_schema(cls) -> dict[str, Any]:
                         },
                         "memory_type": {
                             "type": "string",
-                            "enum": ["episodic", "semantic", "message"],
-                            "description": "Type of memory: 'episodic' (events/experiences), 'semantic' (facts/preferences), 'message' (conversation snippets)",
+                            "enum": ["episodic", "semantic"],
+                            "description": "Type of memory: 'episodic' (events/experiences), 'semantic' (facts/preferences)",
                         },
                         "topics": {
                             "type": "array",
@@ -1595,8 +1599,8 @@ def edit_long_term_memory_tool_schema(cls) -> dict[str, Any]:
                         },
                         "memory_type": {
                             "type": "string",
-                            "enum": ["episodic", "semantic", "message"],
-                            "description": "Updated memory type: 'episodic' (events/experiences), 'semantic' (facts/preferences), 'message' (conversation snippets)",
+                            "enum": ["episodic", "semantic"],
+                            "description": "Updated memory type: 'episodic' (events/experiences), 'semantic' (facts/preferences)",
                         },
                         "namespace": {
                             "type": "string",
@@ -1620,6 +1624,67 @@ def edit_long_term_memory_tool_schema(cls) -> dict[str, Any]:
             },
         }
 
+    @classmethod
+    def create_long_term_memory_tool_schema(cls) -> dict[str, Any]:
+        """
+        Get OpenAI-compatible tool schema for creating long-term memories directly.
+
+        Returns:
+            Tool schema dictionary compatible with OpenAI tool calling format
+        """
+        return {
+            "type": "function",
+            "function": {
+                "name": "create_long_term_memory",
+                "description": (
+                    "Create long-term memories directly for immediate storage and retrieval. "
+                    "Use this for important information that should be permanently stored without going through working memory. "
+                    "This is the 'eager' approach - memories are created immediately in long-term storage. "
+                    "Examples: User preferences, important facts, key events that need to be searchable right away. "
+                    "For episodic memories, include event_date in ISO format."
+                ),
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "memories": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "text": {
+                                        "type": "string",
+                                        "description": "The memory content to store",
+                                    },
+                                    "memory_type": {
+                                        "type": "string",
+                                        "enum": ["episodic", "semantic"],
+                                        "description": "Type of memory: 'episodic' (events/experiences), 'semantic' (facts/preferences)",
+                                    },
+                                    "topics": {
+                                        "type": "array",
+                                        "items": {"type": "string"},
+                                        "description": "Optional topics for categorization",
+                                    },
+                                    "entities": {
+                                        "type": "array",
+                                        "items": {"type": "string"},
+                                        "description": "Optional entities mentioned in the memory",
+                                    },
+                                    "event_date": {
+                                        "type": "string",
+                                        "description": "Optional event date for episodic memories (ISO 8601 format: '2024-01-15T14:30:00Z')",
+                                    },
+                                },
+                                "required": ["text", "memory_type"],
+                            },
+                            "description": "List of memories to create",
+                        },
+                    },
+                    "required": ["memories"],
+                },
+            },
+        }
+
     @classmethod
     def delete_long_term_memories_tool_schema(cls) -> dict[str, Any]:
         """
@@ -1674,6 +1739,7 @@ def get_all_memory_tool_schemas(cls) -> Sequence[dict[str, Any]]:
             cls.get_add_memory_tool_schema(),
             cls.get_update_memory_data_tool_schema(),
             cls.get_long_term_memory_tool_schema(),
+            cls.create_long_term_memory_tool_schema(),
             cls.edit_long_term_memory_tool_schema(),
             cls.delete_long_term_memories_tool_schema(),
             cls.get_current_datetime_tool_schema(),
@@ -1706,6 +1772,7 @@ def get_all_memory_tool_schemas_anthropic(cls) -> Sequence[dict[str, Any]]:
             cls.get_add_memory_tool_schema_anthropic(),
             cls.get_update_memory_data_tool_schema_anthropic(),
             cls.get_long_term_memory_tool_schema_anthropic(),
+            cls.create_long_term_memory_tool_schema_anthropic(),
             cls.edit_long_term_memory_tool_schema_anthropic(),
             cls.delete_long_term_memories_tool_schema_anthropic(),
             cls.get_current_datetime_tool_schema_anthropic(),
@@ -1764,6 +1831,12 @@ def get_long_term_memory_tool_schema_anthropic(cls) -> dict[str, Any]:
         openai_schema = cls.get_long_term_memory_tool_schema()
         return cls._convert_openai_to_anthropic_schema(openai_schema)
 
+    @classmethod
+    def create_long_term_memory_tool_schema_anthropic(cls) -> dict[str, Any]:
+        """Get create long-term memory tool schema in Anthropic format."""
+        openai_schema = cls.create_long_term_memory_tool_schema()
+        return cls._convert_openai_to_anthropic_schema(openai_schema)
+
     @classmethod
     def edit_long_term_memory_tool_schema_anthropic(cls) -> dict[str, Any]:
         """Get edit long-term memory tool schema in Anthropic format."""
@@ -2143,6 +2216,11 @@ async def resolve_function_call(
             elif function_name == "get_long_term_memory":
                 result = await self._resolve_get_long_term_memory(args)
 
+            elif function_name == "create_long_term_memory":
+                result = await self._resolve_create_long_term_memory(
+                    args, effective_namespace, user_id
+                )
+
             elif function_name == "edit_long_term_memory":
                 result = await self._resolve_edit_long_term_memory(args)
 
@@ -2287,6 +2365,40 @@ async def _resolve_get_long_term_memory(
         result = await self.get_long_term_memory(memory_id=memory_id)
         return {"memory": result}
 
+    async def _resolve_create_long_term_memory(
+        self, args: dict[str, Any], namespace: str | None, user_id: str | None = None
+    ) -> dict[str, Any]:
+        """Resolve create_long_term_memory function call."""
+        memories_data = args.get("memories")
+        if not memories_data:
+            raise ValueError(
+                "memories parameter is required for create_long_term_memory"
+            )
+
+        # Convert dict memories to ClientMemoryRecord objects
+        from .models import ClientMemoryRecord, MemoryTypeEnum
+
+        memories = []
+        for memory_data in memories_data:
+            # Apply defaults
+            if namespace and "namespace" not in memory_data:
+                memory_data["namespace"] = namespace
+            if user_id and "user_id" not in memory_data:
+                memory_data["user_id"] = user_id
+
+            # Convert memory_type string to enum if needed
+            if "memory_type" in memory_data:
+                memory_data["memory_type"] = MemoryTypeEnum(memory_data["memory_type"])
+
+            memory = ClientMemoryRecord(**memory_data)
+            memories.append(memory)
+
+        result = await self.create_long_term_memory(memories)
+        return {
+            "status": result.status,
+            "message": f"Created {len(memories)} memories successfully",
+        }
+
     async def _resolve_edit_long_term_memory(
         self, args: dict[str, Any]
     ) -> dict[str, Any]:
@@ -2757,7 +2869,7 @@ async def memory_prompt(
         context_window_max: int | None = None,
         long_term_search: dict[str, Any] | None = None,
         user_id: str | None = None,
-        optimize_query: bool = True,
+        optimize_query: bool = False,
     ) -> dict[str, Any]:
         """
         Hydrate a user query with memory context and return a prompt ready to send to an LLM.
@@ -2861,7 +2973,7 @@ async def hydrate_memory_prompt(
         memory_type: dict[str, Any] | None = None,
         limit: int = 10,
         offset: int = 0,
-        optimize_query: bool = True,
+        optimize_query: bool = False,
     ) -> dict[str, Any]:
         """
         Hydrate a user query with long-term memory context using filters.