Agent Memory

Building Memory-Aware Agents

Ai agent:

An Al agent is a computational entity that perceives its environment through inputs, reasons and plans using a
large language model as its cognitive engine, takes actions through tools and integrations, and is augmented
with persistent memory to store, retrieve, and apply knowledge across interactions

AI Agent memeory

Agent memory refers to the system of architectural components, control mechanisms, tools and
software harness that enables an Al agent to persistently store, organize, retrieve, and reuse
information across time, interactions, and execution contexts, ensuring temporal and contextual
continuity, even across fragmented interactions

the reason why Memeory in Agent

stateless agent

无状态agent, 一轮游，llm只根据输入给出输出
缺点：
无法处理长周期任务
没有跨session的上下文意识
不能学习和更新最新的能力
过长的prompt 造成操作成本较高

memory-augmented agent/conversation agent

记忆增强的agent,将之会话存储起来，会后续提问，提供更多信息
优点：
可处理长时任务
可以跨session保持上下文
提高处理效率，降低token成本
更适合在多步骤工作流中使用

beyond conversation agent

除了将会话内容进行存储
还需要考虑以下问题
对话窗口是有限的，用户关系不是
不是所有的有用信息都在一个会话中
agent 需要一个结构化的，可查询的知识，不止是对话日志

agent memory forms

RAG + MEMORY

传统RAG处理流程

具备memory能力的agent的处理流程

the agent memory core

The primary data infrastructure component of an agent system, responsible for managing the complete lifecycle of agent memory.
This database layer handles persistent storage，efficient retrieval, and memory operations that enable agents to adapt to new information,
learn apry from interactions, and maintain consistent Datd performance across sessions.

contructing the memory manager

存储层分两部分，存储核(数据库) 和存储管理
为agent对话连续性，长时记忆以及信息能力更新的提供帮助

Memory Manager

A Memory Manager is the control logic in the Agent Stack that decides
what becomes memory, how it’s structured, how it’s updated, and when it should be recalled during execution.

存储类型

不同的记忆形式，有不同的存储类型，存储需求不同进而对应不同操作方法

存储操作分类

• Deterministic： Memory reads/writes that run automatically on a fixed schedule or predefined condition， independent of the agent‘s judgment.
  确定性，由固定代码执行的操作
• Agent Triggered： Memory reads/writes that the agent decides to invoke based on its own real-time assessment of need.
  不确定性，由agent 自主决定什么时候调用什么方法进行什么操作

A key design decision in memory engineering is determining which operations should be Deterministic (executed automatically by code) versus Agent-Triggered (decided by the LLM at runtime).

• A deterministic memory operation is one that runs based on system rules, not the model’s discretion. It is executed every time (or under clearly defined, non-negotiable conditions) so the system behaves predictably.
• An agent-triggered memory operation runs only when the model decides it’s necessary, based on intent and situation.

Operation	Deterministic	Agent-Triggered
read_conversational_memory()	✅	❌
read_knowledge_base()	✅	❌
read_workflow()	✅	❌
read_entity()	✅	❌
read_summary_context()	❌	✅
write_conversational_memory()	✅	❌
write_workflow()	✅	❌
write_entity()	❌	✅
search_tavily()	❌	✅
expand_summary()	❌	✅
summarize_and_store()	❌	✅
read_toolbox()	✅	✅

Deterministic memory operations run:

• every turn, or
• under explicit, fixed conditions (e.g., “always at the start of the agent loop”, “always after tool execution”)

Why Deterministic Retrieval Is Useful

Memory retrieval is commonly run at the start of each agent loop because:

1. Context bootstrapping is non-negotiable

   • The agent needs prior context to remain consistent and avoid repeating mistakes.
   • Without deterministic retrieval, the agent behaves “stateless” and starts from scratch.

2. The agent can’t choose to look up what it doesn’t know exists

   • If the agent must decide whether to check memory, it must guess what’s stored.
   • This creates a chicken-and-egg problem: you need memory to know which memory you need.

3. Predictability

   • Always loading memory produces consistent behavior and makes the system easier to evaluate and debug.

Why Deterministic Storage Is Useful

Persisting conversations, workflows, and entities is often deterministic because:

1. Reliability

   • You don’t want the agent to “forget to save” important information.
   • If continuity matters, persistence must be consistent.

2. Completeness

   • Every interaction should be recorded to avoid gaps.
   • Selective saving creates missing context that later breaks long-horizon tasks.

3. Reduced cognitive load

   • The model should focus on task execution, not memory bookkeeping.

Advantages of Deterministic Memory Operations

• Predictable behavior across runs and turns
• Stronger continuity (fewer “stateless resets”)
• Fewer missed memories (higher reliability)
• Easier debugging and evaluation (clear expectations of what should be loaded/saved)

How Tool Calls Fit In

External tool calls (e.g., web search, external DB lookups, expensive summarization jobs) are typically agent-triggered because:

1. Intent matters

   • Only the agent can judge whether extra information is needed.
   • Automatically using tools for every query is wasteful.

2. Cost considerations

   • Tools often introduce latency and may incur API costs.
   • The agent should call tools only when the expected value is high.

3. Judgment required

   • Choosing what to search for or what to expand requires understanding the user’s goal.

---

three terms

Memory Unit

A Memory Unit is the smallest atomic piece of stored information,
represented with a minimal set of attributes
so it can be captured, retrieved, and updated by a memory-augmented agent.

Context engineering

Context engineering is the practice of optimally selecting and
shaping the information placed into an LLM context window
so it can perform a task reliably-while explicitly accounting for context window limits and model constraints.

Memory engineering

The engineering discipline focused on designing, building,
and maintaining memory systems for Al agents.
It encompasses the storage, retrieval，classification, and lifecycle management of agent memory.

memory aware agent

练习

Step	Description
1. Initialize Embeddings	Load a HuggingFace embedding model to convert text into vectors
2. Create Vector Store	Set up an Oracle-backed vector store with distance strategy
3. Create Index	Build an HNSW index for fast similarity search
4. Add Documents	Store text with metadata in the vector database
5. Query	Search for similar documents using natural language
6. Filter Results	Use metadata filters to narrow down search results

Key Components

• OracleVS: LangChain’s Oracle vector store integration
• HuggingFaceEmbeddings: Converts text to 768-dimensional vectors
• DistanceStrategy.EUCLIDEAN_DISTANCE: Measures similarity between vectors
• HNSW Index: Speeds up similarity search with graph-based nearest-neighbor traversal

These tables will be created in Oracle Database to persist agent memory.

Memory Types We’ll Implement

Memory Type	Human Analogy	Purpose	Storage	Retrieval Strategies Used
Conversational	Short-term memory	Chat history per thread	SQL Table	Exact match by thread_id
Knowledge Base	Long-term semantic memory	Facts, documents, search results	Vector Store	Semantic similarity search
Workflow	Procedural memory	Learned action patterns	Vector Store	Semantic similarity search + metadata filtering
Toolbox	Skill memory	Available tools & capabilities	Vector Store	Semantic similarity search
Entity	Episodic memory	People, places, systems mentioned	Vector Store	Semantic similarity search
Summary	Compressed memory	Condensed context for long conversations	Vector Store	Semantic similarity search (with optional ID filter)
Tool Log	Execution audit trail	Raw tool inputs/outputs and execution status	SQL Table	Exact match by thread_id + timestamp ordering

The MemoryManager class is the central abstraction that unifies all memory operations. It provides a clean interface for reading and writing to different memory types, hiding the complexity of SQL queries and vector store operations. It is a single class that manages 7 types of memory with consistent read/write patterns:

Memory Type	Storage	Write Method	Read Method
Conversational	SQL Table	write_conversational_memory()	read_conversational_memory()
Knowledge Base	Vector Store	write_knowledge_base()	read_knowledge_base()
Workflow	Vector Store	write_workflow()	read_workflow()
Toolbox	Vector Store	write_toolbox()	read_toolbox()
Entity	Vector Store	write_entity()	read_entity()
Summary	Vector Store	write_summary()	read_summary_memory(), read_summary_context()
Tool Log	SQL Table	write_tool_log()	read_tool_logs()

实验： AgentMemoryCore

Scaling agent tool use with semantic tool memory

原始tool use 流程

缺点
大量使用tool 工具，不仅会占用context空间，造成token 成本提升，还会造成上下文迷惑，工具选择降级(响应的内容反而使模型性能下降), 延时增加

Problem	Impact
Context bloat	Tool definitions consume tokens, leaving less room for actual content
Tool selection failure	LLMs struggle to choose the right tool when presented with too many options
Increased latency	More tokens = slower inference
Higher costs	More tokens = higher API costs

Model providers like OpenAI and Anthropic typically recommend limiting the number of tools exposed to an LLM (often 10-20 max for reliable selection).

解决办法一：
将tool 信息不注册到上下文中，编码后存在数据库中，当用户提问时，从数据库中查找topk可用tool 再调用使用

解决办法二：
在方法一基础上，对tool 存储单元信息通过llm 进行优化，在数据库中存储优化后的名称和描述
优点：
LLM增强工具
高信号嵌入文本, 方便llm更好查找
语义工具检索
更高的召回率 + 更好的可分离性

The Solution: Semantic Tool Retrieval

The Toolbox class solves this by treating tools as a searchable memory:

1. Register hundreds of tools — Store all available tools with their descriptions and embeddings
2. Retrieve only relevant tools — At inference time, use vector search to find tools semantically relevant to the current query
3. Pass a focused toolset — Only the retrieved tools (typically 3-5) are passed to the LLM

This approach means your system can scale to hundreds of tools while the LLM only sees the most relevant ones for each query.

How the Code Works

The Toolbox class uses docstrings as the retrieval key:

User Query → Embed Query → Vector Search → Find tools with similar docstrings → Return relevant tools

Component	Purpose
Toolbox (from helper.py)	Shared class used across lessons to register and retrieve tools
ToolMetadata (inside helper.py)	Stores tool name, description, signature, parameters
_augment_docstring()	Uses LLM to improve the docstring for better retrieval
_generate_queries()	Creates synthetic queries that would trigger this tool
register_tool()	Decorator that stores tool with its embedding in the toolbox

When you call memory_manager.read_toolbox(query), it performs a similarity search to find tools whose docstrings are semantically similar to the query.

the Toolbox uses embeddings to map natural-language queries to the most relevant tools. This means tool retrieval is semantic: the agent can discover capabilities even when the query wording does not exactly match a tool name.

// 在toolbox 里面注册 tool 
from tavily import TavilyClient
from datetime import datetime

tavily_client = TavilyClient()

# When `augment=True`, the `Toolbox` sends both the **original docstring** and the **function's source code** to an LLM, 
# which produces a richer, more detailed description. 
# This enriched text is what gets embedded and stored — improving semantic separability and retrieval recall.


@toolbox.register_tool(augment=True)
def search_tavily(query: str, max_results: int = 5):
    """
    Use this function to search the web and store the results in the knowledge base.
    """
    response = tavily_client.search(query=query, max_results=max_results)
    results = response.get("results", [])

    # Write each result to the knowledge base
    for result in results:
        # Create the text content to embed
        text = f"Title: {result.get('title', '')}\nContent: {result.get('content', '')}\nURL: {result.get('url', '')}"
        
        # Create metadata
        metadata = {
            "title": result.get("title", ""),
            "url": result.get("url", ""),
            "score": result.get("score", 0),
            "source_type": "tavily_search",
            "query": query,
            "timestamp": datetime.now().isoformat()
        }
        
        # Write to knowledge base
        memory_manager.write_knowledge_base(text, metadata)

    return results

// 获取tool 的源码和描述，用llm augment

import inspect

# Original docstring (what the developer wrote - just one line)
original = ("Use this function to search the web"
            " and store the results in the"
            " knowledge base.")

# Get the actual source code of the function
fn = toolbox._tools_by_name["search_tavily"]
source = inspect.getsource(fn)  // 上面注册的代码

print("ORIGINAL DOCSTRING:")
print(f'  "{original}"')
print()

# The LLM reads both the docstring AND the source code
augmented = toolbox._augment_docstring(original, source)

print("AUGMENTED DOCSTRING (LLM-enhanced):")
print(f"  {augmented}")

toolBOX
实验： 基于tool memory unit优化的存储方案

Memory operations: extraction,consolidation,and self-updating memory

处理原始交互信息为持久知识

Context Window Reduction
Context Window Reduction is the process of shrinking the amount of information placed in an LLM’s context window,
by summarizing, compressing，deduplicating, or filtering content,
while preserving the signals needed for the current task.

Context Window Reduction 有以下两种方式
Context Summarization

Context Summarization

上下文总结，通过提取关键，相关，高识别度高价值信息，摒弃低价值，无关，冗余信息，减少context 大小

Context summarization is the process of compressing content into a shorter representation that preserves the most salient, task-relevant information from the original.

Summarized content is injected into a clean context window.
For certain tasks, retrieving summaries via semantic search provides the LLM with high-signal context.
But naive summarization is a lossy technique

上下文总结有缺点： 容易造成信息丢失

Context Compaction

上下文压缩，将context 放到数据库中，把数据库当外部组件使用，在大模型里注册数据库有哪些信息，如果有需要，可以去数据库获取全量信息

Workflow Memory

Workflow memory is the agent’s ability to persist and reuse the state and structure of work over time,
so multi-step tasks can be continued, resumed, audited，or repeated reliably.

将明确的工作流顺利也同样存储起来，当下次遇到同样问题，直接按历史存储的工作流顺去做就行，减少思考时间，提高产出效率

｛
"workflow_name"："get_current_weather"，
"user_request"： "Get me the current weather"，
"steps"：［
｛ "step"： 1， "action"： "Get current user location"， "type"：
"tool_calI"，"tool"："get_user_location"，"input"： ｛｝，
"output"：｛
"lat"：51.76，"lon"：-0.24 ｝，"status" ： "OK" ｝，
｛ "step"： 2，"action"： "Use weather application tool"， "type"：
"tool_cal1"，"tool"："weather_api"，"input"：｛｝，"output"：｛
"'provider"："weather_app" ｝，"status"： "OK" ｝，
｛ "step"： 3，"action"： "Pass the lat/long into application
tool"，"tyPe"："tool_call"，"tool"："weather_api"，"input"：｛
"lat"：51.76，"1on"：-0.24 ｝，"output"： null，"status"： "OK" ｝，
｛"step"： 4，"action" ： "Get the current weather"， "type"：
"tool_call"，"tool"："weather_api"，"input"：｛ "lat"： 51.76，
"lon"：-0.24 ｝，"output"： ｛ "temp_c"： 7.2，"condition"： "Cloudy"
｝，"status"： "OK" ｝，
（"step"： 5， "action"： "Return weather to user as response"，
"type"："assistant_response"，"tool"：null，"input"： null，
"output"： ｛"text"："It's 7°C and cloudy right now." ｝，"status"：
"OK" ｝
］
｝

练习

Large Language Models have finite context windows. When conversations grow long, we face a critical challenge: how do we preserve important information while staying within token limits?

This section implements the core memory consolidation pipeline:

Long Conversation → Monitor Usage → Summarize → Store Summary → Mark Original as Processed

Why This Matters

Problem	Solution
Context overflow crashes the agent	Monitor token usage and summarize proactively
Summaries lose important details	Capture technical, emotional, and entity information
Can’t access original conversation	Store summary ID links back to original messages
Re-summarizing already processed messages	Mark messages with summary_id after processing

Summarization Functions

The summarization pipeline captures four types of information:

1. Technical Information — Facts, code, configurations, solutions
2. Emotional Context — Tone, sentiment, urgency levels
3. Entities & References — People, systems, projects mentioned
4. Action Items & Decisions — Next steps, agreements, pending tasks

小结

Capability	Implementation
Monitor	calculate_context_usage() tracks token consumption
Summarize	summarise_context_window() extracts structured information
Store	Summaries persist in SUMMARY_MEMORY with links to originals
Expand	expand_summary() tool retrieves original conversations
Self-Update	mark_as_summarized() prevents re-processing

Key Insight: Memory consolidation isn’t just about compression—it’s about structured extraction that preserves technical details, emotional context, entities, and action items.

实验： 利用context 压缩还原减少上下文

Memory Aware Agent

agnet loop

A cyclical, iterative execution pattern inside a single agent run/turn where an agent repeatedly：

1. assembles context （instructions, conversation state, retrieved memory, tool outputs, relevant data）
2. invokes an LLM to reason/decide, and then acts （responds, calls tools, writes memory/state, or updates the plan），until a stop condition is met,
   e.g.， a final answer is produced, a goal is completed, an error/timeout occurs, or the agent explicitly decides to exit.

练习

• Integrate all memory types (conversational, semantic, workflow, entity, summary, tool logs) into a unified agent
• Implement context window management with automatic summarization
• Build an agent loop that retrieves relevant context before each response
• Use Just-In-Time (JIT) retrieval to expand summaries on demand

Key Concepts

Concept	Description
Memory Aware Agent	An agent that reads from and writes to persistent memory stores during execution
Context Engineering	Dynamically building the optimal context window for each query
Just-In-Time Retrieval	Fetching detailed information only when the agent needs it
Automatic Summarization	Compressing context when usage exceeds thresholds

小结

Capability	Implementation
Reads Memory	Retrieves from 7 memory types before each response (tool logs remain JIT by default)
Manages Context	Monitors tokens, summarizes when >80% capacity
Uses Tools	Semantic search selects relevant tools per query
Persists Learning	Saves conversations, workflows, entities, and raw tool logs
Expands On-Demand	JIT retrieval via expand_summary() tool

Key Insight: A memory-aware agent doesn’t just respond to queries—it learns from each interaction. Information discovered, decisions made, and patterns executed are all persisted, making the agent more capable over time.

实验： 具备上下文总结长时记忆能力的智能体