agent memory

Author: ilvalerione

skills/neuron-agent/SKILL.md

@@ -306,7 +306,59 @@ declares that identity — the agent adopts it, and a disagreement with an
 explicit `threadId:` throws. `Agent::getThreadId(): ?string` reads the
 resolved identity back; null means the run is not findable by its thread.
 
-### Memory Types
+### Long-term Memory
+
+Why configure memory on the Agent: chat history and long-term memory belong to
+the same conversation. Wiring them once prevents nodes and middleware from
+clearing one store while leaving stale information in the other.
+
+Pass the application's memory implementation with `setMemory()` before the
+Agent starts:
+
+```php
+use NeuronAI\Chat\History\SQLChatHistory;
+
+$agent = MyAgent::make(threadId: $threadId)
+    ->setChatHistory(new SQLChatHistory($pdo))
+    ->setMemory($memory);
+
+$state = $agent->chat(new UserMessage($input));
+```
+
+The order of `setChatHistory()` and `setMemory()` does not matter. Do not create
+`MemoryAwareChatHistory` yourself: the framework wraps the configured history
+internally and gives that same instance to all Agent nodes and middleware.
+
+For class-based configuration, use the lazy hook:
+
+```php
+use NeuronAI\Agent\Memory\MemoryInterface;
+
+class MyAgent extends Agent
+{
+    protected function memory(): ?MemoryInterface
+    {
+        return new ProjectMemory(/* ... */);
+    }
+}
+```
+
+An explicit `setMemory()` call takes precedence over `memory()`. Memory must be
+configured before the Agent graph is composed or execution starts; late
+configuration throws an `AgentException` instead of leaving already-created
+nodes with a stale history instance.
+
+When any node or middleware calls `flushAll()` on chat history, the framework
+first calls `$memory->forget($threadId)` and then clears the chat history. This
+also applies to `Summarization` and custom middleware. If forgetting memory
+fails, chat history is not cleared and the exception is propagated. Use
+`flushAll()` only when both the conversation history and its long-term memory
+should be reset.
+
+Without `setMemory()` or the `memory()` hook, chat history works exactly as
+before.
+
+### Chat History Backends
 - `InMemoryChatHistory` - Default, session-based
 - `FileChatHistory` - Persist to file
 - `SQLChatHistory` - Database-backed

src/Agent/AGENTS.md

@@ -199,6 +199,49 @@ O(1) instead of embedding the conversation. Consequences:
   response; `AgentState::getSteps()` reports the current execution cycle's
   messages only (transient, available even on an interrupted final state).
 
+### Memory-aware history wiring
+
+Long-term memory is configured on the Agent, not on individual nodes or
+middleware:
+
+```php
+$agent = SupportAgent::make(threadId: $threadId)
+    ->setChatHistory($history)
+    ->setMemory($memory);
+```
+
+`setMemory(MemoryInterface $memory)` makes the Agent wrap its chat history in
+the internal `MemoryAwareChatHistory` decorator. Developers must not construct
+or attach this decorator themselves. The Agent creates it once and injects the
+same effective history into every node, so middleware reading
+`$node->getChatHistory()` participates automatically. Calling `setMemory()`
+before or after `setChatHistory()` produces the same result.
+
+Subclasses may provide the dependency through the lazy hook instead:
+
+```php
+protected function memory(): ?MemoryInterface
+{
+    return new ProjectMemory(/* ... */);
+}
+```
+
+An explicit `setMemory()` call wins over the hook. Configure memory before the
+Agent graph is composed or execution begins; changing it afterwards throws an
+`AgentException`, because already-composed nodes would otherwise keep a stale
+history dependency.
+
+`ChatHistoryInterface::flushAll()` is the shared destructive boundary. On a
+memory-aware Agent it first calls `MemoryInterface::forget($threadId)` and only
+then clears chat history. This covers calls made by built-in middleware such as
+`Summarization` and by developer middleware without adding a separate callback
+or event. If forgetting fails, the chat history remains untouched and the
+exception propagates. Consequently, custom code must call `flushAll()` only
+when both stores should be reset for that thread.
+
+Without configured memory, `getChatHistory()` returns the original history and
+Agent behavior is unchanged.
+
 ## Persistence & Tool Approval
 
 `ToolNode` gates tool execution behind human approval — there is no middleware

src/Agent/Agent.php

@@ -8,6 +8,8 @@
 use NeuronAI\Agent\Events\AgentStartEvent;
 use NeuronAI\Agent\Events\AIInferenceEvent;
 use NeuronAI\Agent\Events\ToolCallEvent;
+use NeuronAI\Agent\Memory\MemoryAwareChatHistory;
+use NeuronAI\Agent\Memory\MemoryInterface;
 use NeuronAI\Agent\Nodes\ChatNode;
 use NeuronAI\Agent\Nodes\ParallelToolNode;
 use NeuronAI\Agent\Nodes\StartNode;
@@ -42,6 +44,16 @@ class Agent extends Workflow implements AgentInterface
 
     protected ChatHistoryInterface $chatHistory;
 
+    /**
+     * The history instance shared by the composed nodes. When memory is
+     * configured this is a decorator around the developer-supplied history.
+     */
+    protected ?ChatHistoryInterface $effectiveChatHistory = null;
+
+    protected ?MemoryInterface $memory = null;
+
+    protected bool $memoryResolved = false;
+
     /**
      * The conversation this run belongs to, and the run's declared workflow
      * ID. Assigned exactly once through adoptThreadId() and NEVER generated —
@@ -109,6 +121,42 @@ protected function attachChatHistory(ChatHistoryInterface $chatHistory): void
         }
 
         $this->chatHistory = $chatHistory;
+        $this->effectiveChatHistory = null;
+    }
+
+    /**
+     * Provide the default long-term memory implementation. Subclasses may
+     * override this hook; null keeps the Agent memory-free.
+     */
+    protected function memory(): ?MemoryInterface
+    {
+        return null;
+    }
+
+    /**
+     * Configure long-term memory before the Agent graph is composed.
+     */
+    public function setMemory(MemoryInterface $memory): self
+    {
+        if ($this->eventNodeMap !== []) {
+            throw new AgentException('Memory must be configured before the Agent starts executing.');
+        }
+
+        $this->memory = $memory;
+        $this->memoryResolved = true;
+        $this->effectiveChatHistory = null;
+
+        return $this;
+    }
+
+    public function getMemory(): ?MemoryInterface
+    {
+        if (!$this->memoryResolved) {
+            $this->memory = $this->memory();
+            $this->memoryResolved = true;
+        }
+
+        return $this->memory;
     }
 
     /**
@@ -139,7 +187,14 @@ public function getChatHistory(): ChatHistoryInterface
             $this->attachChatHistory($this->chatHistory());
         }
 
-        return $this->chatHistory;
+        if ($this->effectiveChatHistory === null) {
+            $memory = $this->getMemory();
+            $this->effectiveChatHistory = $memory instanceof MemoryInterface
+                ? new MemoryAwareChatHistory($this->chatHistory, $memory)
+                : $this->chatHistory;
+        }
+
+        return $this->effectiveChatHistory;
     }
 
     /**

src/Agent/AgentInterface.php

@@ -4,14 +4,15 @@
 
 namespace NeuronAI\Agent;
 
+use Generator;
+use NeuronAI\Agent\Memory\MemoryInterface;
 use NeuronAI\Chat\History\ChatHistoryInterface;
 use NeuronAI\Chat\Messages\Message;
 use NeuronAI\Chat\Messages\Stream\Adapters\StreamAdapterInterface;
 use NeuronAI\Chat\Messages\SystemMessage;
 use NeuronAI\Providers\AIProviderInterface;
 use NeuronAI\Tools\ToolInterface;
 use NeuronAI\Tools\Toolkits\ToolkitInterface;
-use Generator;
 
 interface AgentInterface
 {
@@ -42,6 +43,10 @@ public function setChatHistory(ChatHistoryInterface $chatHistory): AgentInterfac
 
     public function getChatHistory(): ChatHistoryInterface;
 
+    public function setMemory(MemoryInterface $memory): AgentInterface;
+
+    public function getMemory(): ?MemoryInterface;
+
     /**
      * The agent's thread identity — the conversation this run belongs to and
      * the run's declared workflow ID — or null when the run is not

src/Agent/Memory/MemoryAwareChatHistory.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NeuronAI\Agent\Memory;
+
+use NeuronAI\Chat\History\ChatHistoryInterface;
+use NeuronAI\Chat\Messages\Message;
+use NeuronAI\Exceptions\ChatHistoryException;
+
+/**
+ * Internal decorator that keeps explicit conversation deletion consistent
+ * across chat history and long-term memory.
+ */
+final class MemoryAwareChatHistory implements ChatHistoryInterface
+{
+    public function __construct(
+        protected ChatHistoryInterface $history,
+        protected MemoryInterface $memory,
+    ) {
+    }
+
+    public function setThreadId(string $threadId): void
+    {
+        $this->history->setThreadId($threadId);
+    }
+
+    public function getThreadId(): ?string
+    {
+        return $this->history->getThreadId();
+    }
+
+    public function addMessage(Message $message): ChatHistoryInterface
+    {
+        $this->history->addMessage($message);
+
+        return $this;
+    }
+
+    public function getMessages(): array
+    {
+        return $this->history->getMessages();
+    }
+
+    public function getLastMessage(): Message|false
+    {
+        return $this->history->getLastMessage();
+    }
+
+    public function flushAll(): ChatHistoryInterface
+    {
+        $threadId = $this->getThreadId() ?? throw new ChatHistoryException(
+            'Cannot clear memory for an unbound chat history.'
+        );
+
+        // Forget first: an unavailable memory store must not leave recalled
+        // content behind while the chat history appears to be deleted.
+        $this->memory->forget($threadId);
+        $this->history->flushAll();
+
+        return $this;
+    }
+
+    public function calculateTotalUsage(): int
+    {
+        return $this->history->calculateTotalUsage();
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->history->jsonSerialize();
+    }
+}

src/Agent/Memory/MemoryInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NeuronAI\Agent\Memory;
+
+interface MemoryInterface
+{
+    /**
+     * Permanently remove every memory associated with a conversation.
+     */
+    public function forget(string $threadId): void;
+}