Memory System

+------------------------------------------------------------------+
|                       Memory Service (:8002)                      |
+------------------------------------------------------------------+
|                                                                    |
|  +------------------+  +--------------------+  +----------------+ |
|  | Working Memory   |  | Episodic Memory    |  | Injection      | |
|  | (Redis Hash)     |  | (pgvector)         |  | Ledger         | |
|  |                  |  |                    |  | (Redis Hash)   | |
|  | Key-value per    |  | Conversation       |  |                | |
|  | conversation     |  | summaries with     |  | Tracks what    | |
|  | 24h TTL          |  | vector embeddings  |  | has been       | |
|  | 64KB max         |  | Semantic search    |  | injected       | |
|  +--------+---------+  +---------+----------+  +--------+-------+ |
|           |                      |                       |         |
|           v                      v                       v         |
|        Redis 7              PostgreSQL 15             Redis 7      |
+------------------------------------------------------------------+

class WorkingMemory:
    async def get(self, conversation_id: str) -> dict[str, Any]:
        """Get all fields. Refreshes TTL on access."""
 
    async def set(self, conversation_id: str, data: dict[str, Any]) -> None:
        """Set one or more fields. Checks 64KB size limit."""
 
    async def delete(self, conversation_id: str, fields: list[str] | None) -> None:
        """Delete specific fields or entire working memory."""
 
    async def set_scratchpad(self, conversation_id: str, content: str) -> None:
    async def get_scratchpad(self, conversation_id: str) -> str | None:
    async def set_entities(self, conversation_id: str, entities: list[dict]) -> None:
    async def get_entities(self, conversation_id: str) -> list[dict]:

CREATE TABLE episodic_memories (
    id UUID PRIMARY KEY,
    agent_id VARCHAR(100) NOT NULL,
    user_id VARCHAR(100),
    conversation_id VARCHAR(100) NOT NULL,
    summary TEXT NOT NULL,
    key_decisions JSONB,
    entities_mentioned JSONB,
    tools_called JSONB,
    embedding vector(1536),
    created_at TIMESTAMPTZ DEFAULT NOW()
);
 
CREATE INDEX idx_episodic_embedding ON episodic_memories
    USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

# Semantic search query
SELECT id, summary, key_decisions, entities_mentioned,
       1 - (embedding <=> $1::vector) AS similarity
FROM episodic_memories
WHERE agent_id = $2
ORDER BY embedding <=> $1::vector
LIMIT $3

[Episodic Memory -- Relevant Past Conversations]
  - (similarity: 0.87) Previously filed Rule 37 exception for Mitchell Ranch 2H...
  - (similarity: 0.72) Discussed spacing requirements for Spraberry Trend wells...

class RedisManager:
    # Key-value helpers
    async def get(self, key: str) -> str | None
    async def set(self, key: str, value: str, ex: int | None = None) -> None
    async def delete(self, key: str) -> None
 
    # Injection ledger helpers
    def _ledger_key(self, conversation_id: str) -> str:
        return f"skill:ledger:{conversation_id}"
 
    async def ledger_has(self, conversation_id: str, item_key: str) -> bool
    async def ledger_mark(self, conversation_id: str, item_key: str, value: str = "1") -> None
    async def ledger_get_all(self, conversation_id: str) -> dict[str, str]

memory_node
  |
  +-- GET /working-memory/{conversation_id}     --> scratchpad, entities
  |
  +-- POST /episodic/search                     --> similar past conversations
  |
  +-- (injection ledger is used later by skill_inject_node)