運用 EverOS 與 Milvus 建立長期代理記憶體
EverOS是一個專為 AI 代理設計、以 Markdown 為核心的記憶系統。它能從對話中提取持久的記憶，將 Markdown 作為權威來源，並建立可搜尋的衍生索引。
在本教學中，我們將打造一位能記住不同對話中發布決策的專案助理。我們會加入關於「Project Atlas」發布的對話，以及與其他專案無關的對話。EverOS 將使用大型語言模型（LLM）來提取記憶，而Milvus則負責儲存用於混合搜尋的 BM25 索引和向量索引。
Conversations
|
v
EverOS + LLM ------> Markdown memory files
|
| embedding model
v
Milvus ------> BM25 + vector hybrid search
大型語言模型（LLM）與嵌入模型各自承擔不同的職責。大型語言模型將對話轉化為結構化記憶；嵌入模型則將這些記憶以及後續的搜尋查詢轉換為向量。本教學中的基礎混合搜尋無需使用重新排序模型。
先決條件
您需要：
- Python 3.12 或更新版本
uv- 已運作的Milvus 伺服器
- 一個OpenAI API 金鑰
本教學將連線至http://localhost:19530 上的 Milvus 伺服器。EverOS 亦支援透過相同的 URI 和憑證設定連線至Zilliz Cloud。其 Milvus 後端需指定遠端端點，且不接受 Milvus Lite 的檔案路徑。
安裝 EverOS
建立本機專案並安裝 EverOS 及其可選的 Milvus 依賴項：
mkdir everos-milvus-demo
cd everos-milvus-demo
uv init --bare --python 3.12
uv add "everos[milvus]"
此指令刻意未指定版本，因此新安裝時會自動取得最新相容的 EverOS 發行版。
為本教學初始化一個獨立的記憶體根目錄：
export EVEROS_ROOT="$PWD/everos-data"
uv run everos init --root "$EVEROS_ROOT"
EverOS 會在此目錄下建立everos.toml 和ome.toml 。它也會將解壓縮後的記憶體檔案寫入此處。
設定 OpenAI 與 Milvus
透過環境變數設定 OpenAI API 金鑰並配置 EverOS：
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export MILVUS_URI="http://localhost:19530"
export EVEROS_INDEX__BACKEND="milvus"
export EVEROS_MILVUS__URI="$MILVUS_URI"
export EVEROS_MILVUS__COLLECTION_PREFIX="everos_bootcamp"
export EVEROS_LLM__MODEL="gpt-5.4-mini"
export EVEROS_LLM__API_KEY="$OPENAI_API_KEY"
export EVEROS_LLM__BASE_URL="https://api.openai.com/v1"
export EVEROS_EMBEDDING__MODEL="text-embedding-3-small"
export EVEROS_EMBEDDING__API_KEY="$OPENAI_API_KEY"
export EVEROS_EMBEDDING__BASE_URL="https://api.openai.com/v1"
export EVEROS_EMBEDDING__DIMENSIONS="1024"
export EVEROS_MEMORIZE__MODE="chat"
EverOS 同時使用 OpenAI 進行記憶體擷取與嵌入向量處理。text-embedding-3-small 預設會返回1536 維度的結果，但 EverOS 會將設定的dimensions 值轉發給 OpenAI。本教學中請求1024 維度的結果，以配合由 EverOS 管理的 Milvus 資料結構。
chat 的記憶體模式使本範例能專注於使用者記憶體。EverOS 負責管理 Milvus 集合及其資料結構，因此您無需自行建立。
啟動 EverOS
啟動 EverOS HTTP 伺服器：
uv run everos server start --root "$EVEROS_ROOT"
請保持此終端機開啟。EverOS 會在啟動時連線至 Milvus，並使用已設定的前綴建立七個衍生索引集合。
在同一專案目錄中開啟另一個終端機，並檢查服務狀態：
curl http://127.0.0.1:8000/health
參考輸出：
{
"status": "ok",
"version": "1.3.0",
"capabilities": {
"llm": true,
"embed": true,
"rerank": false,
"multimodal_llm": false,
"parser": true
},
"cascade": {
"healthy": true,
"pending": 0
}
}
回應中包含額外的健康狀態欄位。本教學中重要的數值包括status: "ok" 、llm: true 、embed: true 以及cascade.healthy: true 。
新增專案對話
以下 Python 程式會向 EverOS 傳送十個獨立的對話。Atlas 設有獨立的啟動與回滾討論。其中八個關於其他專案的對話會作為干擾項，使後續的搜尋必須辨識出正確的專案記憶。
將以下程式碼儲存為add_memories.py ：
import json
import time
from urllib.request import Request, urlopen
API_URL = "http://127.0.0.1:8000/api/v2/memory"
NOW = int(time.time() * 1000)
conversations = [
(
"atlas-release",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW,
"content": (
"For Project Atlas, we decided to launch with a 10% canary "
"on September 30. Promote to all users only after the checkout "
"error rate stays below 1% for 30 minutes."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 1_000,
"content": (
"Understood. I will remember the Atlas launch date, canary "
"percentage, and promotion gate."
),
},
],
),
(
"atlas-rollback",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 10_000,
"content": (
"The Atlas rollback owner is Priya. Roll back immediately if "
"checkout errors exceed 2% for five minutes, and keep the "
"previous container image available for 24 hours."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 11_000,
"content": (
"Got it. Priya owns rollback, with the 2% five-minute trigger "
"and a 24-hour image retention window."
),
},
],
),
(
"orion-pricing",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 20_000,
"content": (
"Project Orion will test annual billing with the education "
"segment. The pricing review is scheduled for October 12."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 21_000,
"content": (
"I will remember Orion's annual billing experiment and October "
"pricing review."
),
},
],
),
(
"vega-mobile",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 30_000,
"content": (
"For Project Vega, the mobile team chose offline drafts as the "
"next milestone. Elena will review the interaction design on "
"October 18."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 31_000,
"content": (
"Noted. Vega's next milestone is offline drafts, followed by "
"Elena's design review."
),
},
],
),
(
"nova-warehouse",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 40_000,
"content": (
"Project Nova will migrate the analytics warehouse to Iceberg. "
"Marcus owns the checksum rehearsal scheduled for October 22."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 41_000,
"content": (
"I will remember Nova's warehouse migration and Marcus's "
"checksum rehearsal."
),
},
],
),
(
"helios-support",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 50_000,
"content": (
"Project Helios needs weekend support coverage for the APAC "
"region. Imani will publish the rotation schedule on November 1."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 51_000,
"content": (
"Noted. Helios needs APAC weekend coverage, and Imani owns the "
"rotation schedule."
),
},
],
),
(
"luna-onboarding",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 60_000,
"content": (
"Project Luna will replace the onboarding tour with a checklist. "
"The localized copy is due from the content team on October 25."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 61_000,
"content": (
"I will remember Luna's checklist approach and the localization "
"deadline."
),
},
],
),
(
"aurora-observability",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 70_000,
"content": (
"Project Aurora will retain detailed telemetry for 30 days. "
"The operations team should alert after three consecutive "
"heartbeat misses."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 71_000,
"content": (
"Understood. Aurora keeps 30 days of telemetry and alerts after "
"three missed heartbeats."
),
},
],
),
(
"comet-invoices",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 80_000,
"content": (
"Project Comet will add downloadable invoice PDFs for enterprise "
"accounts. Finance will approve the tax-field layout on October 28."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 81_000,
"content": (
"Noted. Comet covers enterprise invoice PDFs and an October tax "
"layout review."
),
},
],
),
(
"solstice-research",
[
{
"sender_id": "maya",
"sender_name": "Maya",
"role": "user",
"timestamp": NOW + 90_000,
"content": (
"Project Solstice is prototyping voice notes for field researchers. "
"The research team will interview 12 participants in November."
),
},
{
"sender_id": "assistant",
"role": "assistant",
"timestamp": NOW + 91_000,
"content": (
"I will remember Solstice's voice-note prototype and the planned "
"participant interviews."
),
},
],
),
]
def post(path, payload):
request = Request(
f"{API_URL}/{path}",
data=json.dumps(payload).encode(),
headers={"Content-Type": "application/json"},
method="POST",
)
with urlopen(request, timeout=300) as response:
return json.load(response)["data"]
for session_id, messages in conversations:
added = post(
"add",
{
"session_id": session_id,
"app_id": "project-assistant",
"project_id": "launch-planning",
"messages": messages,
"defer_extraction": True,
},
)
flushed = post(
"flush",
{
"session_id": session_id,
"app_id": "project-assistant",
"project_id": "launch-planning",
},
)
print(f"{session_id}: {added['status']} -> {flushed['status']}")
從專案目錄執行該程式：
uv run python add_memories.py
參考輸出：
atlas-release: accumulated -> extracted
atlas-rollback: accumulated -> extracted
orion-pricing: accumulated -> extracted
vega-mobile: accumulated -> extracted
nova-warehouse: accumulated -> extracted
helios-support: accumulated -> extracted
luna-onboarding: accumulated -> extracted
aurora-observability: accumulated -> extracted
comet-invoices: accumulated -> extracted
solstice-research: accumulated -> extracted
將 `defer_extraction ` 設定為 `true `，即可將每段對話儲存至持久化緩衝區，而無需要求大型語言模型（LLM）偵測邊界。下列 `/flush ` 呼叫會標記該會話的結束，並觸發一次提取。隨後，EverOS 會將提取的片段寫入 Markdown 格式，並以非同步方式將其嵌入 Milvus 索引中。
檢視 Markdown 記憶體
生成的片段檔案儲存於應用程式、專案及使用者範圍之下：
find "$EVEROS_ROOT/project-assistant/launch-planning/users/maya/episodes" \
-type f -name "*.md"
參考輸出（檔案名稱中的日期反映您執行範例的時間）：
everos-data/project-assistant/launch-planning/users/maya/episodes/episode-2026-09-08.md
開啟檔案即可查看由 LLM 提取的記憶片段。以下為節錄內容：
## ep_20260908_00000001
**owner_id**: maya
**session_id**: atlas-release
**sender_ids**: [maya, assistant]
### Subject
Maya's Project Atlas Launch Decision: September 30 Canary and Promotion Criteria
### Content
Maya decided that Project Atlas would launch with a 10% canary on September 30.
The promotion to all users would occur only after the checkout error rate remained
below 1% for 30 minutes.
由於記憶片段是由 LLM 提取的，因此確切的措辭、識別碼和時間戳記可能會有所不同。原始的 Markdown 檔案仍是可信賴的權威來源；Milvus 索引可根據這些檔案重新建置。
搜尋記憶片段
在 Atlas 正式上線前，請使用混合搜尋來查詢應記住的內容。將以下程式碼儲存為search_memories.py ：
import json
import time
from urllib.request import Request, urlopen
URL = "http://127.0.0.1:8000/api/v2/memory/search"
payload = {
"user_id": "maya",
"app_id": "project-assistant",
"project_id": "launch-planning",
"query": "What should I remember before Atlas goes live?",
"method": "hybrid",
"top_k": 4,
}
def search():
request = Request(
URL,
data=json.dumps(payload).encode(),
headers={"Content-Type": "application/json"},
method="POST",
)
with urlopen(request, timeout=300) as response:
return json.load(response)["data"]["episodes"]
expected_sessions = {"atlas-release", "atlas-rollback"}
for _ in range(30):
episodes = search()
top_results = episodes[:2]
if {episode["session_id"] for episode in top_results} == expected_sessions:
break
time.sleep(2)
else:
raise RuntimeError("The expected Atlas memories were not indexed in time")
for rank, episode in enumerate(top_results, start=1):
print(f"{rank}. {episode['session_id']} | score={episode['score']:.3f}")
print(f" {episode['subject']}")
執行搜尋：
uv run python search_memories.py
參考輸出結果（分數與措辭可能有所不同）：
1. atlas-release | score=0.492
Project Atlas Launch Plan: 10% Canary Rollout on September 30 with Error Rate Gate
2. atlas-rollback | score=0.400
Atlas Rollback Plan Details: Priya as Owner, 2% Error Trigger, 24-Hour Image Retention
兩則 Atlas 對話皆排在八則無關對話之前。EverOS 會將查詢傳送至 OpenAI 嵌入端點，並要求 Milvus 在 Maya 的應用程式與專案範圍內提供 BM25 及向量候選結果，最後將這兩組結果清單進行融合。
檢視 Milvus 集合
EverOS 會針對每種受支援的衍生記憶體類型建立一個集合。使用MilvusClient 列出其行數：
import os
from pymilvus import MilvusClient
prefix = "everos_bootcamp"
client = MilvusClient(uri=os.environ.get("MILVUS_URI", "http://localhost:19530"))
memory_kinds = [
"agent_case",
"agent_skill",
"atomic_fact",
"episode",
"foresight",
"knowledge_topic",
"user_profile",
]
for kind in memory_kinds:
name = f"{prefix}_{kind}"
if client.has_collection(collection_name=name):
result = client.query(
collection_name=name,
filter="",
output_fields=["count(*)"],
)
print(f"{kind}: {result[0]['count(*)']} rows")
client.close()
參考已驗證執行結果：
agent_case: 0 rows
agent_skill: 0 rows
atomic_fact: 50 rows
episode: 10 rows
foresight: 0 rows
knowledge_topic: 0 rows
user_profile: 1 rows
原子事實的確切數量可能因 LLM 輸出而異。這十筆事件記錄對應於十段已沖洗的對話。其餘集合則適用於本聚焦範例未涉及的 EverOS 記憶體模式與功能。
使用其他 Milvus 部署
若要使用其他 Milvus Server 端點或Zilliz Cloud，請更新EVEROS_MILVUS__URI 。當端點需要驗證時，請設定EVEROS_MILVUS__TOKEN 。資料導入與搜尋程式碼保持不變。
結論
透過將 EverOS 與 Milvus 結合，您可以將對話轉化為持久的記憶，並透過關鍵字和語義訊號進行檢索。您亦可套用相同的模式，為您的使用者、專案和工作流程，賦予助理及其他代理型應用程式長期記憶能力。
