Hướng dẫn Supermemory: Thêm bộ nhớ bền vững cho AI Agents

Supermemory là gì?

Mô tả ngắn gọn nhất, Supermemory là một API bộ nhớ cho AI agent. Khi bạn cung cấp cho Supermemory các chuỗi mô tả người dùng của mình, sau đó nó trả về một bức tranh cô đọng về người dùng đó là ai và họ vừa làm gì gần đây. Việc nhúng, lập chỉ mục và truy xuất đều chạy bên trong Supermemory, nên mã agent của bạn vẫn gọn nhẹ.

Bộ đánh giá LongMemEval kiểm tra mức độ một hệ thống bộ nhớ trả lời câu hỏi tốt thế nào trên lịch sử trò chuyện dài. Supermemory nhớ đúng 81,6% sự kiện. Zep, hệ thống xếp sau, đạt 71,2%, chênh 10 điểm—tương đương khoảng 1 câu trả lời đúng thêm trên mỗi 10 câu hỏi. Kho mã nguồn mở có hơn 22k sao GitHub, thêm một tín hiệu về mức độ sử dụng thực tế.

Bộ nhớ vs RAG

Hầu hết độc giả tìm đến công cụ bộ nhớ cho agent đều từng dùng RAG. Thật hữu ích khi đặt Supermemory cạnh RAG. RAG và bộ nhớ giải quyết các bài toán khác nhau, và thường cùng tồn tại trong một agent.

Một hệ thống RAG trỏ đến một tập tài liệu mà nhà phát triển chuẩn bị một lần: sổ tay sản phẩm, bài viết hỗ trợ, tài liệu nội bộ. Tập này được nạp lúc triển khai, truy vấn lúc chạy, và hiếm khi thay đổi. Agent dùng nó để trả lời các câu hỏi mà bản thân sản phẩm biết câu trả lời.

Một hệ thống bộ nhớ thì trỏ vào người dùng. Supermemory ghi các sự kiện riêng của người dùng khi agent trò chuyện với họ, và kho lưu trữ lớn dần sau mỗi cuộc trò chuyện. Agent dùng nó để trả lời những câu hỏi chỉ người dùng mới có câu trả lời, như sở thích, lịch sử và hoạt động gần đây.

Trong một sản phẩm thực tế, cả hai chạy song song. RAG trên kho tri thức công ty trả lời "chính sách hoàn tiền của chúng ta là gì?". Supermemory phục vụ câu hỏi của người dùng: "Tuần trước tôi đẩy ngực được bao nhiêu?" Cùng một agent, hai kho dữ liệu, hai nhiệm vụ.

Hồ sơ người dùng: sự kiện tĩnh và động

Ý tưởng chính của Supermemory là hồ sơ người dùng. Mỗi bản ghi được phân vào hai nhóm: sự kiện tĩnh hiếm khi thay đổi và sự kiện động về hoạt động hiện tại. Mẫu lặp lại sẽ được thăng hạng thành tĩnh. Hoạt động gần đây nằm ở động.

Khi agent đọc hồ sơ, một lần gọi trả về cả hai nhóm cùng các mẩu ký ức phù hợp.

Việc tách này quan trọng vì các sự kiện tĩnh và động trả lời các câu hỏi khác nhau về cùng một người dùng:

Đọc hàng đầu tiên. Phần tĩnh cho biết người dùng tập thế nào: tại nhà, với thiết bị họ có. Điều đó không đổi theo tuần. Phần động nói họ đang tập trung vào gì ngay lúc này: thân trên, chu kỳ này.

Một công cụ gợi ý buổi tập cần cả hai. Phần tĩnh loại trừ các bài chỉ tập ở phòng gym, phần động chọn buổi tập hôm nay.

Đằng sau hồ sơ đó, Supermemory làm bốn việc mà bình thường bạn phải tự xây: lưu thô ký ức, nhúng mỗi mẩu, chạy tìm kiếm tương đồng khi đọc, và trích xuất sự kiện hồ sơ từ nội dung đã ghi. Cả bốn việc đều không xuất hiện trong mã của bạn.

Mỗi ký ức được gắn nhãn bằng một chuỗi do nhà phát triển chọn. Mỗi lần đọc truyền lại cùng chuỗi đó để giới hạn dữ liệu trả về. Trình huấn luyện hardcode một nhãn vì một người dùng là đủ để minh họa hồ sơ hoạt động ra sao. Ứng dụng thực tế tính nhãn từ người dùng đã xác thực, như JWT của họ.

Thiết lập môi trường Supermemory của bạn

Trình huấn luyện cần hai khóa API (Supermemory và OpenAI) và một dự án Python với ba phụ thuộc. Một script kiểm tra nhanh sẽ xác nhận cả hai khóa hoạt động trước khi bất kỳ mã agent nào dùng đến chúng.

Lấy khóa API của bạn

Khóa API Supermemory nằm tại console.supermemory.ai, KHÔNG PHẢI app.supermemory.ai. Tiểu miền app là sản phẩm bộ nhớ cho người dùng cuối (lưu ghi chú, duyệt không gian của bạn). Nó không có trang khóa API. Bỏ qua nó và vào thẳng console.

Tại console.supermemory.ai:

1. Đăng nhập.

2. Nhấp API Keys trong thanh bên.

3. Nhấp Create API Key.

4. Đặt tên (bản demo trong hướng dẫn dùng datacamp-tutorial).

5. Sao chép khóa tạo ra. Nó bắt đầu bằng sm_.

Bạn cũng cần một khóa OpenAI cho các cuộc gọi LLM của agent. Lấy một khóa tại platform.openai.com/api-keys nếu bạn chưa có.

Tạo tệp .env ở thư mục gốc dự án với cả hai khóa. Đừng commit tệp này.

SUPERMEMORY_API_KEY=sm_your_key_here
OPENAI_API_KEY=sk-your_key_here

Gói miễn phí của Supermemory đủ cho hướng dẫn này mà không cần nhập thông tin thanh toán. Giới hạn cụ thể nằm trên trang giá.

Cài đặt phụ thuộc

Hướng dẫn dùng uv cho việc thiết lập dự án và chạy. Nếu bạn chưa có uv, hãy cài một lần bằng lệnh một dòng từ astral.sh/uv.

Khởi tạo dự án:

uv init supermemory-trainer
cd supermemory-trainer

Xóa README.md được tạo tự động bởi uv init. Tệp hello.py tạo sẵn sẽ bị ghi đè ở bước tiếp theo, nên cứ để đó.

Thêm ba phụ thuộc:

• supermemory==3.37.0 là client bộ nhớ, cố định phiên bản đã được kiểm chứng cho hướng dẫn này.

• openai-agents là OpenAI Agents SDK. Tên gói có dấu gạch nối, đường dẫn import là agents.

• python-dotenv đọc tệp .env bạn vừa tạo.

uv add supermemory==3.37.0 openai-agents python-dotenv

pyproject.toml thu được:

[project]
name = "supermemory-trainer"
version = "0.1.0"
description = "Personal exercise trainer agent built with Supermemory and the OpenAI Agents SDK."
requires-python = ">=3.10"
dependencies = [
	"openai-agents>=0.10.2",
	"python-dotenv>=1.2.1",
	"supermemory==3.37.0",
]

Xác minh thiết lập của bạn

Trước khi viết bất kỳ mã agent nào, hãy xem Supermemory làm việc một lần với một câu đơn. Script dưới đây gửi một sự kiện đến Supermemory, đợi pipeline xử lý, rồi đọc hồ sơ trả về. Nếu chạy trơn tru, các khóa đã hoạt động và SDK truy cập được. Kết quả cũng cho bạn cái nhìn đầu tiên về cách Supermemory xử lý văn bản thô.

Mở hello.py ở thư mục gốc dự án và thay phần thân tạo sẵn bằng các import và một lệnh ghi:

import time
 
from dotenv import load_dotenv
from supermemory import Supermemory
 
load_dotenv()
 
client = Supermemory()
USER_ID = "demo_warmup"
 
response = client.add(
	content="The user is learning Supermemory by building a personal trainer agent.",
	container_tag=USER_ID,
)
print(f"client.add() -> id={response.id} status={response.status}")

load_dotenv() đọc khóa API từ .env vào biến môi trường trước khi khởi tạo Supermemory(). Client sẽ tự lấy SUPERMEMORY_API_KEY. Giá trị container_tag="demo_warmup" giới hạn sự kiện này vào một người dùng tạm.

Giờ thêm bước đợi và bước đọc ở cuối cùng một tệp:

print("Waiting 20 seconds for processing...")
time.sleep(20)
 
prof = client.profile(container_tag=USER_ID, q="learning")
print(f"profile.static  ({len(prof.profile.static)}): {prof.profile.static}")
print(f"profile.dynamic ({len(prof.profile.dynamic)}): {prof.profile.dynamic}")
print(f"search_results.results ({len(prof.search_results.results)}):")
for r in prof.search_results.results[:3]:
	print(f"  - {r['memory']} (similarity={r['similarity']:.3f})")

Lệnh ngủ 20 giây cho pipeline nhúng-và-trích của Supermemory có thời gian xử lý ký ức mới. Nếu không có, lần đọc sẽ không trả về gì và script trông như bị lỗi dù không phải vậy.

Chạy tệp:

uv run python hello.py

Kết quả kỳ vọng:

client.add() -> id=zNLsJBrY1PZupAeZ3Qn6EL status=queued
Waiting 20 seconds for processing...
profile.static  (0): []
profile.dynamic (1): ['Building a personal trainer agent to learn Supermemory.']
search_results.results (1):
  - Building a personal trainer agent to learn Supermemory. (similarity=0.650)

Ba chi tiết quan trọng trong kết quả này. client.add() trả về ngay với status="queued", vì Supermemory xử lý tài liệu bất đồng bộ. 20 giây chờ bao phủ pipeline nhúng-và-trích. Đến lúc đọc, câu thô đã thành một mẩu ký ức có thể tìm kiếm.

Dòng đáng chú ý là profile.dynamic. Đầu vào là câu "The user is learning Supermemory by building a personal trainer agent." Kết quả là sự kiện động 'Building a personal trainer agent to learn Supermemory.' Supermemory đã viết lại câu ở ngôi thứ ba thành sự kiện ngôi thứ nhất về người dùng. Đó là trình trích xuất hồ sơ đang làm việc.

profile.static là danh sách rỗng. Sự kiện tĩnh được hợp nhất chậm, sau khi tích lũy một vài bản ghi liên quan, nên một lần ghi khởi động không tạo ra kết quả. Công cụ gợi ý của trình huấn luyện đã tính đến điều này và coi static là phần thưởng chứ không phải đảm bảo.

Xây dựng Supermemory Agent: Huấn luyện viên bài tập cá nhân bằng Python

Trình huấn luyện bọc client.add() và client.profile() thành hai công cụ cho agent, để việc đọc và ghi diễn ra tự động khi người dùng trò chuyện. Lịch sử buổi tập rất phù hợp với bộ nhớ. Thiết bị, chấn thương và mức tạ gần đây không nằm trong dữ liệu huấn luyện của LLM, và chúng tích lũy theo từng phiên.

Cấu trúc dự án và agent

Trình huấn luyện đủ nhỏ để toàn bộ dự án gói gọn trong hai tệp Python cộng với pyproject.toml bạn đã có:

supermemory-trainer/
├── .env            	# your real keys (gitignored)
├── .env.example    	# placeholders, committed
├── .gitignore
├── .python-version
├── main.py         	# agent definition, system prompt, REPL loop
├── pyproject.toml
└── tools.py        	# log_workout and suggest_next_session

tools.py chứa hai công cụ dựa trên bộ nhớ mà bạn sẽ viết tiếp. log_workout ghi một buổi tập vào Supermemory qua client.add(). suggest_next_session đọc hồ sơ người dùng qua client.profile(). main.py import cả hai và kết nối agent.

Phần lớn main.py là boilerplate của OpenAI Agents SDK. Một câu trong system prompt làm công việc của Supermemory: mọi sự kiện về người dùng phải quay về qua các lời gọi công cụ. Agent được dặn rằng nó không có bộ nhớ riêng. Quy tắc duy nhất đó biến trình huấn luyện thành hệ thống có bộ nhớ nền tảng.

Mở main.py và bắt đầu với các import và system prompt:

import asyncio
 
from agents import Agent, Runner, SQLiteSession
 
from tools import log_workout, suggest_next_session
 
SYSTEM_PROMPT = """You are a personal exercise trainer who logs the user's
workouts and recommends what to do next.
 
You have no memory of the user's history on your own. Every fact about the
user lives in Supermemory and reaches you only through tool calls.
 
Two rules, no exceptions:
 
1. Whenever the user reports completing a workout, call log_workout immediately, before responding. Extract the exercise, sets, reps, weight, and any notes from what they said. If a value is missing, ask one short follow-up question instead of guessing. After logging, confirm in one short sentence and stop. Do NOT recommend the next session unless the user asks for one.
 
2. When the user explicitly asks what to do next (or asks for a recommendation, suggestion, or plan), call suggest_next_session first. Never recommend from your own training data. The tool returns the user's
 recent activity, stable preferences, and matching past sessions. Reference those facts directly in your reply.
 
Keep replies concise (2-4 sentences). Be specific: name the exercise, sets, reps, and weight. Honor any injuries or equipment constraints the tool surfaces.
"""

Cả hai quy tắc trong system prompt đều dẫn mô hình đi qua Supermemory. 

Quy tắc 1 buộc gọi log_workout mỗi khi người dùng báo đã hoàn thành buổi tập, để mọi buổi tập đều vào kho bộ nhớ. Quy tắc 2 buộc đọc suggest_next_session trước bất kỳ khuyến nghị nào, để mọi khuyến nghị đều dựa trên những gì Supermemory biết. 

Bỏ qua các quy tắc đó, agent sẽ trả lời từ dữ liệu huấn luyện của nó, làm mất ý nghĩa của lớp bộ nhớ.

Giờ định nghĩa agent và vòng lặp chat trong cùng tệp:

def build_agent() -> Agent:
	return Agent(
    	name="Trainer",
    	instructions=SYSTEM_PROMPT,
    	tools=[log_workout, suggest_next_session],
    	model="gpt-5",
	)
 
 
async def chat() -> None:
	agent = build_agent()
	session = SQLiteSession(session_id="trainer-cli")
 
	print("Trainer ready. Type a message, or 'exit' to quit.\n")
	while True:
    	try:
        	message = input("You: ").strip()
    	except (EOFError, KeyboardInterrupt):
        	print()
        	break
    	if not message:
        	continue
    	if message.lower() in {"exit", "quit"}:
        	break
 
    	result = await Runner.run(agent, message, session=session)
    	print(f"\nTrainer: {result.final_output}\n")
 
 
if __name__ == "__main__":
	asyncio.run(chat())

Hai dòng trong khối đó đáng chú ý. tools=[log_workout, suggest_next_session] đăng ký hai công cụ dựa trên bộ nhớ. Bộ trang trí @function_tool trên mỗi công cụ (trong tools.py) cho SDK biết chúng có thể được gọi. Thiếu decorator, agent sẽ không có công cụ nào lúc chạy, dù lệnh khởi tạo vẫn thành công.

SQLiteSession(session_id="trainer-cli") giữ lịch sử lượt ngắn hạn trong tiến trình Python đang chạy. Supermemory giữ sự kiện dài hạn của người dùng qua các tiến trình. Dừng tiến trình Python sẽ làm mất phiên SQLite, nhưng dữ liệu Supermemory vẫn còn.

Quan trọng: Chạy main.py như một script, không phải trong ô Jupyter, vì vòng lặp sự kiện của Jupyter xung đột với asyncio.run(). Client đồng bộ Supermemory() hoạt động bên trong các hàm công cụ async vì Agents SDK chạy công cụ trong thread pool. Để biết thêm về SDK, xem hướng dẫn OpenAI Agents SDK.

Viết công cụ ghi nhật ký buổi tập

log_workout là phía ghi của bộ nhớ agent. Hàm nhận các tham số có cấu trúc từ agent: tên bài tập, số hiệp, số lần, mức tạ và ghi chú tùy chọn. Nó chuyển những thứ đó thành một câu tiếng Anh ngắn và gửi câu này đến Supermemory qua client.add(). Pipeline nhúng-và-trích chạy bên trong Supermemory sau đó và không cần gì thêm từ trình huấn luyện.

Mở tools.py và bắt đầu với các import và một client dùng chung:

from agents import function_tool
from dotenv import load_dotenv
from supermemory import Supermemory
 
load_dotenv()
 
USER_ID = "demo_user"
 
client = Supermemory()

load_dotenv() chạy lúc import để SUPERMEMORY_API_KEY có trong môi trường trước khi khởi tạo Supermemory(). Nếu tạo client trước khi nạp env, bạn sẽ có client chưa xác thực. Lần gọi đầu sẽ trả về 401 gây bối rối. Cả hai hàm công cụ trong tệp này dùng chung một client đó và hằng số USER_ID.

Thêm công cụ ghi bên dưới client:

@function_tool
def log_workout(
	exercise: str,
	sets: int,
	reps: int,
	weight: float,
	notes: str = "",
) -> str:
	"""Log a completed workout to the user's memory.
 
	Args:
    	exercise: Name of the exercise.
    	sets: Number of sets performed.
    	reps: Number of reps per set.
    	weight: Weight in pounds. Pass 0 for bodyweight or cardio.
    	notes: Optional notes about the session.
	"""
	print(f"[log_workout] {exercise=} {sets=} {reps=} {weight=} {notes=}")
 
	content = f"Performed {exercise}: {sets} sets of {reps} reps at {weight} lbs."
	if notes:
    	content += f" Notes: {notes}"
 
	response = client.add(content=content, container_tag=USER_ID)
	print(f"[log_workout] -> id={response.id} status={response.status}")
	return f"Logged {exercise} ({sets}x{reps} @ {weight} lb)."

Chuỗi docstring của @function_tool là thứ LLM nhìn thấy khi quyết định có gọi công cụ hay không. Khối Args: ánh xạ tới mô tả từng tham số. Cả hai là một phần hợp đồng giữa agent và hàm.

Công cụ gửi một câu thuần văn bản đến client.add(), không phải JSON. Trình trích xuất hồ sơ của Supermemory đọc ngôn ngữ tự nhiên và suy diễn sự kiện từ đó. Về mặt kỹ thuật JSON vẫn dùng được, nhưng chất lượng trích xuất giảm vì mô hình không có mạch truyện để tóm lược. "Performed bench press: 4 sets of 5 reps at 185.0 lbs" cho trình trích xuất một câu gọn gàng để xử lý.

Hai lệnh print() ghi mỗi lần gọi công cụ ra terminal: trước là tham số đã phân tích, sau là phản hồi.

[log_workout] exercise='bench press' sets=4 reps=5 weight=185.0 notes=''
[log_workout] -> id=xY7AK3qLzBPx5Vd2HnRf1M status=queued

Giá trị status="queued" khớp với những gì script khởi động trả về trước đó. Bản ghi thô đã được lưu, nhưng client.profile() sẽ không trả về nó như một kết quả tìm kiếm cho đến khi pipeline hoàn tất. Bạn sẽ thêm bước xác minh sau để đợi quá trình đó ổn định.

Viết công cụ gợi ý buổi tập

suggest_next_session là phía đọc, và đây là nơi phép tách tĩnh-động phát huy tác dụng. Một lần gọi client.profile(container_tag=USER_ID, q=focus) trả về ba góc nhìn về người dùng trong một vòng khứ hồi. 

Sở thích ổn định nằm ở profile.static, hoạt động hiện tại ở profile.dynamic, và các ký ức quá khứ phù hợp nhất ở search_results.results. Nhiệm vụ của công cụ là làm phẳng ba góc nhìn đó thành một khối ngữ cảnh mà agent có thể trích dẫn.

Sau vài buổi tập, công cụ tạo ra đầu ra như sau:

Recent activity:
- Trains at home instead of a gym
- Performed deadlift: 3 sets of 5 reps at 225.0 lbs
- Performed 5k run in 26 minutes
- Reports no knee pain during bench press
- Performed bench press: 4 sets of 5 reps at 185.0 lbs
Closest matching past entries:
- Trains at home instead of a gym
- Performed deadlift: 3 sets of 5 reps at 225.0 lbs
- Performed bench press: 4 sets of 5 reps at 185.0 lbs
- Performed 5k run in 26 minutes
- Reports no knee pain during bench press

Agent đọc khối đó và viết khuyến nghị dựa trên lịch sử thực của người dùng. Không có hồ sơ của Supermemory, bạn sẽ phải tự xây cùng ngữ cảnh: tìm kiếm ngữ nghĩa riêng, kho hồ sơ riêng và hợp nhất kết quả. Lệnh gọi đơn client.profile() thay thế cả ba.

Thêm đoạn này vào tools.py bên dưới log_workout:

@function_tool
def suggest_next_session(focus: str) -> str:
	"""Fetch the user's training history and preferences for a given focus.
 
	Returns a context string the agent can use to recommend the next session.
	The agent is responsible for the actual recommendation. This tool only
	surfaces what Supermemory knows about the user.
 
	Args:
    	focus: What the user wants to train next (e.g. "upper body", "legs",
        	"cardio", "today"). Drives semantic search against past logs.
	"""
	print(f"[suggest_next_session] focus={focus!r}")
	profile = client.profile(container_tag=USER_ID, q=focus)
 
	static_facts = profile.profile.static
	dynamic_facts = profile.profile.dynamic
	matches = profile.search_results.results
 
	print(
    	f"[suggest_next_session] static={len(static_facts)} "
    	f"dynamic={len(dynamic_facts)} matches={len(matches)}"
	)
 
	sections = []
	if static_facts:
    	sections.append("Stable preferences and constraints:")
    	sections.extend(f"- {fact}" for fact in static_facts)
	if dynamic_facts:
    	sections.append("Recent activity:")
    	sections.extend(f"- {fact}" for fact in dynamic_facts)
	if matches:
    	sections.append("Closest matching past entries:")
    	for r in matches[:5]:
        	sections.append(f"- {r['memory']}")
 
	if not sections:
    	return (
        	"No prior training history found for this user. "
        	"Ask the user about their goals, equipment, and recent training."
    	)
	return "\n".join(sections)

client.profile(container_tag=USER_ID, q=focus) trả về một đối tượng ProfileResponse. Sau 5 bản ghi ngắn, ba trường công cụ đọc trông như sau:

profile.profile.static        	# [] (list[str])
profile.profile.dynamic       	# ["Performed bench press: 4 sets of 5 reps at 185.0 lbs", ...]
profile.search_results.results	# [{"memory": "...", "similarity": 0.631, ...}, ...] (list[dict])

Mỗi kết quả tìm kiếm là một dict Python, không phải đối tượng Pydantic. Dùng r["memory"] cho văn bản và r["similarity"] cho điểm số. Dict đầy đủ có các khóa sau:

• id

• memory

• rootMemoryId

• metadata

• updatedAt

• version

• similarity

• filepath

• documents

Đoạn r.memory or r.chunk từ trang tích hợp OpenAI Agents SDK của Supermemory gây lỗi AttributeError với supermemory==3.37.0. Dùng cú pháp truy cập bằng ngoặc vuông.

static đang rỗng ở đây, đó là lý do công cụ rẽ nhánh theo if static_facts:. Các nhánh dynamic và search_results làm phần việc chính trong khoảng chục bản ghi đầu tiên.

Supermemory cũng áp dụng một ngưỡng tương đồng mặc định. Một sự kiện bạn chỉ nhắc một lần có thể không quay lại cho mọi truy vấn. 5 bản ghi trên đều trả về với q="today", nhưng chuỗi truy vấn cụ thể hơn có thể trả về ít hơn. Điều kiện if matches: xử lý việc đó mà không lỗi.

Chạy phiên 1: ghi nhật ký buổi tập

Bắt đầu phiên 1 và ghi một vài buổi tập để lấp đầy Supermemory với dữ liệu đọc lại sau này. Chạy script:

uv run python main.py

Ghi đẩy ngực, rồi chạy 5k, rồi deadlift, cộng với một câu về sở thích: "Tôi chỉ tập ở nhà, không đến phòng gym." Agent gọi log_workout một lần cho mỗi buổi, và các dòng print() của công cụ giúp thấy rõ từng lần gọi trong terminal.

Đầu ra minh họa. Câu chữ chính xác của agent bạn có thể khác vì mô hình không xác định.

Ba dòng status=queued là thời điểm Supermemory tiếp quản. Mỗi dòng tương ứng với một tài liệu đang đi qua pipeline nhúng-và-trích ở phía Supermemory. Với các bản ghi ngắn như thế này, tài liệu trở nên có thể tìm qua client.profile() trong khoảng ~12 giây.

Không có gì trong mã của trình huấn luyện đợi điều đó. Agent tiếp tục, và Supermemory hoàn tất công việc ở nền.

Mỗi bản ghi kích hoạt đúng một lần gọi log_workout, và agent dừng lại. Không gợi ý chủ động, không gọi công cụ thừa, không đề xuất tiếp theo. Quy tắc đầu tiên trong system prompt đảm đương việc đó. Không có quy tắc, agent sẽ gợi ý buổi tiếp sau mỗi lần ghi, làm số lần gọi công cụ tăng gấp đôi.

Gõ exit để đóng phiên 1. Tiến trình Python kết thúc, và SQLiteSession biến mất cùng nó. Nhật ký buổi tập và câu về sở thích giờ sống trong Supermemory dưới container_tag="demo_user", tách biệt với script đã ghi chúng.

Xác minh khả năng nhớ và chạy phiên 2

Trước phiên 2, xác nhận rằng các sự kiện từ phiên 1 có thể được truy vấn. Mở một Python REPL mới hoặc lưu đoạn sau thành một script ngắn:

from dotenv import load_dotenv
from supermemory import Supermemory
 
load_dotenv()
client = Supermemory()
 
prof = client.profile(container_tag="demo_user", q="training")
print(f"static  ({len(prof.profile.static)}): {prof.profile.static}")
print(f"dynamic ({len(prof.profile.dynamic)}):")
for fact in prof.profile.dynamic:
	print(f"  - {fact}")
print(f"matches ({len(prof.search_results.results)}):")
for r in prof.search_results.results[:5]:
	print(f"  - {r['memory']} (similarity={r['similarity']:.3f})")

Đầu ra thực tế ghi giữa hai phiên:

static  (0): []
dynamic (5):
  - Trains at home instead of a gym
  - Performed deadlift: 3 sets of 5 reps at 225.0 lbs
  - Performed 5k run in 26 minutes
  - Reports no knee pain during bench press
  - Performed bench press: 4 sets of 5 reps at 185.0 lbs
matches (5):
  - Trains at home instead of a gym (similarity=0.682)
  - Performed deadlift: 3 sets of 5 reps at 225.0 lbs (similarity=0.643)
  - Performed bench press: 4 sets of 5 reps at 185.0 lbs (similarity=0.631)
  - Performed 5k run in 26 minutes (similarity=0.585)
  - Reports no knee pain during bench press (similarity=0.585)

Xem những gì trình trích xuất của Supermemory tạo ra. Người dùng nói một lần, "Tôi chỉ tập ở nhà, không đến phòng gym." Trình trích xuất biến câu đó thành sự kiện động "Trains at home instead of a gym".

Nhật ký đẩy ngực có trường ghi chú về việc không đau đầu gối. Trình trích xuất tách bản ghi đó thành hai sự kiện động: một cho buổi tập, một cho việc không đau.

Bốn bản ghi trở thành năm sự kiện động đã chuẩn hóa cùng năm mẩu ký ức phù hợp với điểm tương đồng từ 0,585 đến 0,682. Không phần tách, chuẩn hóa hay đối sánh nào chạy trong mã của trình huấn luyện. Nếu dynamic trống với bạn, đợi thêm 10 giây và chạy lại đoạn mã. Hàng đợi xử lý đôi khi tăng cao.

Giờ bắt đầu phiên 2 trong một tiến trình hoàn toàn mới:

uv run python main.py

Đây là một trình thông dịch Python mới. Không chia sẻ bộ nhớ với phiên 1. Không cache ấm. Bất cứ thứ gì agent nhớ lại đều đến từ Supermemory.

Gửi một tin nhắn: "Hôm nay tôi nên tập gì?"

Đầu ra ví dụ. Cùng kho bộ nhớ, tiến trình Python mới.

Agent gọi suggest_next_session("today"). Công cụ in static=0 dynamic=5 matches=5. Lần chạy được ghi đã trả lời bằng một buổi tập thân dưới tại nhà (squat, lunge, step-up).

Khuyến nghị khớp với các bản ghi trước vì hồ sơ của Supermemory đã cho agent biết về chúng. Đẩy ngực, deadlift và chạy 5k là thân trên hoặc cardio, và người dùng chỉ tập tại nhà. Cả hai sự kiện quay lại từ cùng một lệnh gọi client.profile(). Lần chạy của bạn sẽ diễn đạt khác vì mô hình không xác định, nhưng đường đi nhớ lại thì như nhau.

Bước tiếp theo cho Supermemory Agent của bạn

Bản demo là một người dùng, hai công cụ và một CLI. Phiên bản thực tế của trình huấn luyện mở rộng theo ba hướng gắn với Supermemory trước khi đụng đến vòng lặp agent.

Phân phạm vi bộ nhớ theo người dùng thực. Hằng số USER_ID = "demo_user" hoạt động cho một người. Ứng dụng sản xuất tính nhãn từ ID người dùng đã xác thực, như container_tag="user_sarah" hoặc container_tag=customer_id. Bộ nhớ giữa các người dùng tách biệt vì mỗi lần đọc đều truyền lại nhãn. Chỉ cần đổi một chỗ trong tools.py, không cần đổi mã khác.

Thêm nhiều công cụ có bộ nhớ nền tảng. Tuần giảm tải, theo dõi PR, và nhắc nhở mobility hàng tuần. Mỗi cái là một hàm @function_tool khác gọi client.add() để ghi và client.profile() để đọc trên cùng container_tag. Hình thức công cụ giữ nguyên. Chỉ nội dung agent ghi và yêu cầu thay đổi.

Xử lý lỗi Supermemory. Bọc client.add() và client.profile() trong try/except supermemory.APIError để lỗi tạm thời từ Supermemory không làm agent sập. Đặt timeout theo yêu cầu nếu agent của bạn chạy trong môi trường hạn chế.

Phần vòng lặp agent độc lập với Supermemory và có thể thay đổi sau. Đặt CLI phía trước bởi Telegram, Discord hoặc Slack, để người dùng nhắn buổi tập và bot gọi Runner.run(). Hoặc đổi khung. Supermemory có tích hợp LangChain nếu ngăn xếp của bạn đã dùng agent LangChain, và mã bộ nhớ không đổi.

Phép tách tĩnh-động cũng phù hợp với các miền khác. 

• Agent hỗ trợ khách hàng: tĩnh = vấn đề đã biết và ưu tiên tài khoản, động = ticket đang mở và liên hệ gần đây. 
• Agent lập trình: tĩnh = ngôn ngữ và framework ưa thích, động = tác vụ hiện tại và tệp vừa chỉnh sửa. 

Phép tách này phù hợp bất cứ khi nào người dùng là nguồn sự thật.

Kết luận

Bạn vừa xây dựng một trình huấn luyện Python với hai công cụ và bộ nhớ bền vững qua các tiến trình. client.add() ghi các buổi tập. client.profile() đọc người dùng thành các sự kiện tĩnh, động và các đối sánh ngữ nghĩa trong một lần gọi, tất cả được giới hạn bởi container_tag. Supermemory thực hiện việc chia mẩu, nhúng, tìm kiếm và trích xuất hồ sơ mà bản demo không cần viết.

Kết hợp với RAG, cùng một agent trả lời câu hỏi về người dùng và sản phẩm. LLM Agents Explained bao quát các mẫu agent rộng hơn, và lộ trình Associate AI Engineer for Developers đi sâu hơn vào các agent có bộ nhớ nền tảng.