Make client-side IDs required in working memory

Author: abrookins

README.md

@@ -28,6 +28,8 @@ A Redis-powered memory server built for AI agents and applications. It manages b
   - Background task processing for memory indexing and promotion
   - Unified search across working memory and long-term memory
 
+For detailed information about memory types, their differences, and when to use each, see the [Memory Types Guide](docs/memory-types.md).
+
 ## Authentication
 
 The Redis Agent Memory Server supports OAuth2/JWT Bearer token authentication for secure API access. It's compatible with Auth0, AWS Cognito, Okta, Azure AD, and other standard OAuth2 providers.

agent_memory_server/api.py

@@ -2,6 +2,7 @@
 from fastapi import APIRouter, Depends, HTTPException
 from mcp.server.fastmcp.prompts import base
 from mcp.types import TextContent
+from ulid import ULID
 
 from agent_memory_server import long_term_memory, working_memory
 from agent_memory_server.auth import UserInfo, get_current_user
@@ -278,6 +279,7 @@ async def put_session_memory(
 
             memories = [
                 MemoryRecord(
+                    id=str(ULID()),
                     session_id=session_id,
                     text=f"{msg.role}: {msg.content}",
                     namespace=updated_memory.namespace,

agent_memory_server/client/api.py

@@ -23,6 +23,7 @@
 )
 from agent_memory_server.models import (
     AckResponse,
+    ClientMemoryRecord,
     CreateMemoryRecordRequest,
     HealthCheckResponse,
     MemoryPromptRequest,
@@ -300,7 +301,7 @@ async def set_working_memory_data(
     async def add_memories_to_working_memory(
         self,
         session_id: str,
-        memories: list[MemoryRecord],
+        memories: list[ClientMemoryRecord | MemoryRecord],
         namespace: str | None = None,
         replace: bool = False,
     ) -> WorkingMemoryResponse:
@@ -368,7 +369,7 @@ async def add_memories_to_working_memory(
         return await self.put_session_memory(session_id, working_memory)
 
     async def create_long_term_memory(
-        self, memories: list[MemoryRecord]
+        self, memories: list[ClientMemoryRecord | MemoryRecord]
     ) -> AckResponse:
         """
         Create long-term memories for later retrieval.

agent_memory_server/long_term_memory.py

@@ -494,7 +494,7 @@ async def compact_long_term_memories(
                         discrete_memory_extracted_value = "t"
 
                     memory_obj = MemoryRecord(
-                        id_=memory_id,
+                        id=memory_id,
                         text=str(memory_data.get("text", "")),
                         user_id=str(memory_data.get("user_id"))
                         if memory_data.get("user_id")
@@ -664,7 +664,7 @@ async def index_long_term_memories(
     async with redis.pipeline(transaction=False) as pipe:
         for idx, vector in enumerate(embeddings):
             memory = processed_memories[idx]
-            id_ = memory.id_ if memory.id_ else str(ULID())
+            id_ = memory.id if memory.id else str(ULID())
             key = Keys.memory_key(id_, memory.namespace)
 
             # Generate memory hash for the memory
@@ -861,7 +861,8 @@ async def search_long_term_memories(
 
         results.append(
             MemoryRecordResult(
-                id_=safe_get(doc, "id_"),
+                id=safe_get(doc, "id_")
+                or safe_get(doc, "id", ""),  # Use id_ or fallback to id
                 text=safe_get(doc, "text", ""),
                 dist=float(safe_get(doc, "vector_distance", 0)),
                 created_at=datetime.fromtimestamp(int(safe_get(doc, "created_at", 0))),
@@ -876,7 +877,6 @@ async def search_long_term_memories(
                 entities=doc_entities,
                 memory_hash=safe_get(doc, "memory_hash"),
                 memory_type=safe_get(doc, "memory_type", "message"),
-                id=safe_get(doc, "id"),
                 persisted_at=datetime.fromtimestamp(
                     int(safe_get(doc, "persisted_at", 0))
                 )
@@ -1049,7 +1049,7 @@ async def search_memories(
                             if text.lower() in memory.text.lower():
                                 working_memory_results.append(
                                     MemoryRecordResult(
-                                        id_=memory.id_ or "",
+                                        id=memory.id or "",  # Use id instead of id_
                                         text=memory.text,
                                         dist=0.0,  # No vector distance for working memory
                                         created_at=memory.created_at or 0,
@@ -1062,7 +1062,6 @@ async def search_memories(
                                         entities=memory.entities or [],
                                         memory_hash="",  # Working memory doesn't have hash
                                         memory_type=memory.memory_type,
-                                        id=memory.id,
                                         persisted_at=memory.persisted_at,
                                         event_date=memory.event_date,
                                     )
@@ -1427,7 +1426,7 @@ async def deduplicate_by_semantic_search(
 
             # Convert back to LongTermMemory
             merged_memory_obj = MemoryRecord(
-                id_=memory.id_ or str(ULID()),
+                id=memory.id or str(ULID()),
                 text=merged_memory["text"],
                 user_id=merged_memory["user_id"],
                 session_id=merged_memory["session_id"],

agent_memory_server/models.py

@@ -5,6 +5,7 @@
 
 from mcp.server.fastmcp.prompts import base
 from pydantic import BaseModel, Field
+from ulid import ULID
 
 from agent_memory_server.config import settings
 from agent_memory_server.filters import (
@@ -78,11 +79,8 @@ class SessionListResponse(BaseModel):
 class MemoryRecord(BaseModel):
     """A memory record"""
 
+    id: str = Field(description="Client-provided ID for deduplication and overwrites")
     text: str
-    id_: str | None = Field(
-        default=None,
-        description="Optional ID for the memory record",
-    )
     session_id: str | None = Field(
         default=None,
         description="Optional session ID for the memory record",
@@ -127,10 +125,6 @@ class MemoryRecord(BaseModel):
         default=MemoryTypeEnum.MESSAGE,
         description="Type of memory",
     )
-    id: str | None = Field(
-        default=None,
-        description="Client-provided ID for deduplication and overwrites",
-    )
     persisted_at: datetime | None = Field(
         default=None,
         description="Server-assigned timestamp when memory was persisted to long-term storage",
@@ -145,6 +139,15 @@ class MemoryRecord(BaseModel):
     )
 
 
+class ClientMemoryRecord(MemoryRecord):
+    """A memory record with a client-provided ID"""
+
+    id: str = Field(
+        default=str(ULID()),
+        description="Client-provided ID for deduplication and overwrites",
+    )
+
+
 class WorkingMemory(BaseModel):
     """Working memory for a session - contains both messages and structured memory records"""
 
@@ -153,7 +156,7 @@ class WorkingMemory(BaseModel):
         default_factory=list,
         description="Conversation messages (role/content pairs)",
     )
-    memories: list[MemoryRecord] = Field(
+    memories: list[MemoryRecord | ClientMemoryRecord] = Field(
         default_factory=list,
         description="Structured memory records for promotion to long-term storage",
     )

agent_memory_server/utils/redis.py

@@ -71,7 +71,7 @@ def get_search_index(
                     "type": "vector",
                     "attrs": {
                         "algorithm": "HNSW",
-                        "dims": vector_dimensions,
+                        "dims": int(vector_dimensions),
                         "distance_metric": distance_metric,
                         "datatype": "float32",
                     },