Agent Memory
Relevant source files
The following files were used as context for generating this wiki page:Agent Memory is a core component of the Loom runtime, designed to provide agents with state persistence, enabling long-running lifecycles and complex, stateful reasoning. It allows agents to store and retrieve information across sessions, from conversational history to structured data like trading plans. The memory system is a key enabler for advanced applications such as the Market Analyst, where agents must remember past decisions to avoid redundant actions and learn from historical outcomes.
The architecture follows Loom's "Brain/Hand" separation principle. Short-term "Working Memory" is managed in Python for rapid iteration within the cognitive loop, while long-term "Persistent Memory" is handled by the robust Rust Core for security and stability. Communication between the agent's brain and the persistent store is facilitated by a dedicated gRPC MemoryService.
Sources: ROADMAP.md, ARCHITECTURE.md, apps/market-analyst/README.md
Architecture Overview
The memory system is structured into distinct tiers, reflecting the different needs of an agent during its cognitive cycle.
This diagram shows the two main parts of the memory system: the Python-side WorkingMemory for immediate context and the Rust-side MemoryStore for long-term persistence, connected via the gRPC Bridge.
Sources: ROADMAP.md, ARCHITECTURE.md, loom-py/src/loom/cognitive/README.md, bridge/src/memory_handler.rs
Memory Tiers
Loom's memory architecture is planned to have multiple tiers to manage information over an agent's lifecycle.
| Tier | Component | Location | Purpose |
|---|---|---|---|
| Working Memory | WorkingMemory class | Python | Holds conversational history and steps for the current task. Volatile. |
| Short-Term Memory | InMemoryMemory | Rust | In-memory persistence for the current session, accessible via gRPC. Used for features like plan de-duplication. |
| Long-Term Memory | RocksDBStore (Planned) | Rust | Persistent, on-disk storage using RocksDB for cross-session memory. |
Sources: ROADMAP.md, loom-py/src/loom/cognitive/README.md, bridge/src/memory_handler.rs
Working Memory (Python)
Working Memory is a short-term, in-memory store used by the CognitiveAgent in Python. It holds the history of the current conversation or task, including user inputs, agent thoughts, and tool outputs. Its primary role is to assemble the context required for the next LLM prompt.
Key characteristics:
- In-Memory: Resides within the Python agent's process.
- Session-Scoped: Data is lost when the agent process terminates.
- Limited Capacity: Typically holds a fixed number of recent items (
max_items).
The WorkingMemory class provides methods to manage this context:
add(role, content): Adds a message from a "user" or "assistant".get_context(max_items): Retrieves the most recent items.to_messages(): Converts the stored items into a message list format suitable for an LLM prompt.
Sources: loom-py/src/loom/cognitive/README.md
Persistent Memory (Rust)
Persistent memory is managed by the Rust Core and is designed for long-term storage and inter-session state. It is exposed to Python agents via the gRPC MemoryService. The current implementation provides an in-memory store (InMemoryMemory), with plans for a RocksDB-backed persistent store.
Memory Service (gRPC)
The MemoryService is a gRPC service defined in memory.proto that provides a formal API for agents to interact with the persistent memory store. The MemoryHandler in the Rust Bridge implements this service.
The following diagram illustrates the sequence of a planner agent saving a trading plan.
MemoryService RPCs
The service provides specialized methods, primarily for the Market Analyst use case, to manage trading plans and executions.
| RPC Method | Request Message | Response Message | Description |
|---|---|---|---|
SavePlan | SavePlanRequest | SavePlanResponse | Saves a new trading plan. |
GetRecentPlans | GetRecentPlansRequest | GetRecentPlansResponse | Retrieves recent plans for a given symbol. |
CheckDuplicate | CheckDuplicateRequest | CheckDuplicateResponse | Checks if a similar plan was made recently. |
MarkExecuted | MarkExecutedRequest | MarkExecutedResponse | Marks a plan as executed for idempotency. |
CheckExecuted | CheckExecutedRequest | CheckExecutedResponse | Checks if a plan has already been executed. |
GetExecutionStats | GetExecutionStatsRequest | GetExecutionStatsResponse | Retrieves statistics about past executions. |
AppendEvent | MemoryWriteRequest | MemoryWriteResponse | Appends a generic event to the memory. |
Retrieve | MemoryRetrieveRequest | MemoryRetrieveResponse | Performs a generic retrieval from memory. |
SummarizeEpisode | MemorySummarizeRequest | MemorySummarizeResponse | Triggers summarization of a recent episode. |
Sources: loom-proto/proto/memory.proto, bridge/src/memory_handler.rs
Data Models
The memory service uses structured Protobuf messages to store data, ensuring consistency between the Python agents and the Rust core.
PlanRecord
This message represents a trading decision made by the planner agent.
| Field | Type | Description |
|---|---|---|
timestamp_ms | int64 | The time the plan was created. |
symbol | string | The trading symbol (e.g., "BTC-USDT"). |
action | string | The recommended action ("BUY", "SELL", "HOLD"). |
confidence | float | The agent's confidence in the plan (0.0 to 1.0). |
reasoning | string | The LLM's reasoning behind the decision. |
plan_hash | string | A hash of the plan's core attributes for de-duplication. |
method | string | The method used to generate the plan ("llm" or "rule-based"). |
metadata | map<string, string> | Additional key-value metadata. |
Sources: loom-proto/proto/memory.proto:14-24
ExecutionRecord
This message logs the outcome of an attempt to execute a PlanRecord.
| Field | Type | Description |
|---|---|---|
timestamp_ms | int64 | The time the execution was attempted. |
plan_hash | string | The hash of the plan that was executed. |
symbol | string | The trading symbol. |
action | string | The action taken. |
confidence | float | The confidence of the original plan. |
status | string | The outcome ("success", "error", "skipped"). |
executed | bool | Whether the trade was actually placed. |
order_id | string | The exchange-provided order ID, if successful. |
order_size_usdt | float | The size of the order in USDT. |
error_message | string | Details of any error that occurred. |
Sources: loom-proto/proto/memory.proto:27-38
Relationship Diagram
The following diagram shows the relationship between plans and executions.
A single PlanRecord can have one or more ExecutionRecords associated with it, linked by the plan_hash.
Sources: loom-proto/proto/memory.proto:14-38
Summary
Loom's Agent Memory system is a sophisticated, multi-tiered framework that provides agents with both short-term contextual awareness and long-term persistent state. By separating volatile working memory in Python from the durable, gRPC-accessible store in Rust, it achieves both flexibility for rapid development and the robustness required for long-running, reliable agentic systems. The structured data models and dedicated service RPCs, particularly for the Market Analyst demo, highlight its capability to support complex, domain-specific memory operations.