Crie memória de longo prazo para agentes com o EverOS e o Milvus
O EverOS é um sistema de memória baseado em Markdown para agentes de IA. Extraia memórias duradouras das conversas, mantenha o Markdown como fonte de referência e crie um índice derivado pesquisável.
Neste tutorial, iremos criar um assistente de projeto que se lembra das decisões de lançamento ao longo de conversas distintas. Iremos adicionar conversas sobre o lançamento do Projeto Atlas, juntamente com conversas não relacionadas sobre outros projetos. O EverOS utilizará um LLM para extrair as memórias, enquanto o Milvus armazena os índices BM25 e vetoriais utilizados para a pesquisa híbrida.
Conversations
|
v
EverOS + LLM ------> Markdown memory files
|
| embedding model
v
Milvus ------> BM25 + vector hybrid search
O LLM e o modelo de incorporação têm responsabilidades diferentes. O LLM transforma uma conversa em memórias estruturadas. O modelo de incorporação converte essas memórias e, posteriormente, as consultas de pesquisa em vetores. A pesquisa híbrida básica neste tutorial não requer um modelo de reclassificação.
Pré-requisitos
É necessário:
- Python 3.12 ou posterior
uv- Um servidor Milvus em funcionamento
- Uma chave da API da OpenAI
Este tutorial estabelece ligação ao servidor Milvus em http://localhost:19530. O EverOS também suporta o Zilliz Cloud através das mesmas definições de URI e token. O seu backend Milvus espera um ponto final remoto e não aceita um caminho de ficheiro do Milvus Lite.
Instalar o EverOS
Crie um projeto local e instale o EverOS com as suas dependências opcionais do Milvus:
mkdir everos-milvus-demo
cd everos-milvus-demo
uv init --bare --python 3.12
uv add "everos[milvus]"
O comando não especifica intencionalmente uma versão, pelo que uma nova instalação irá selecionar a versão mais recente compatível do EverOS.
Inicialize uma raiz de memória separada para o tutorial:
export EVEROS_ROOT="$PWD/everos-data"
uv run everos init --root "$EVEROS_ROOT"
O EverOS cria everos.toml e ome.toml neste diretório. Também irá gravar as memórias extraídas aqui.
Configurar o OpenAI e o Milvus
Defina a chave da API do OpenAI e configure o EverOS através de variáveis de ambiente:
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"
O EverOS utiliza o OpenAI tanto para a extração de memória como para as incorporações. O text-embedding-3-small devolve dimensões 1536 por predefinição, mas o EverOS encaminha o valor dimensions configurado para o OpenAI. Este tutorial solicita dimensões 1024 para corresponder aos esquemas do Milvus geridos pelo EverOS.
O modo de memória chat mantém este exemplo centrado nas memórias dos utilizadores. O EverOS gere as coleções do Milvus e os respetivos esquemas, pelo que não é necessário criá-los manualmente.
Inicie o EverOS
Inicie o servidor HTTP do EverOS:
uv run everos server start --root "$EVEROS_ROOT"
Mantenha este terminal aberto. O EverOS liga-se ao Milvus e cria sete coleções de índices derivados com o prefixo configurado durante o arranque.
Abra outro terminal no mesmo diretório do projeto e verifique o serviço:
curl http://127.0.0.1:8000/health
Saída de referência:
{
"status": "ok",
"version": "1.3.0",
"capabilities": {
"llm": true,
"embed": true,
"rerank": false,
"multimodal_llm": false,
"parser": true
},
"cascade": {
"healthy": true,
"pending": 0
}
}
A resposta contém campos adicionais de integridade. Os valores importantes para este tutorial são status: "ok", llm: true, embed: true e cascade.healthy: true.
Adicionar conversas do projeto
O programa Python seguinte envia dez conversas independentes para o EverOS. O Atlas tem discussões separadas sobre lançamento e reversão. Oito conversas sobre outros projetos servem de distrações, de modo que a pesquisa posterior tenha de identificar as memórias corretas do projeto.
Guarde o código seguinte como « 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']}")
Execute-o a partir do diretório do projeto:
uv run python add_memories.py
Saída de referência:
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
Definir ` defer_extraction ` como ` true ` armazena cada conversa no buffer durável sem pedir ao LLM para detetar um limite. A seguinte chamada ` /flush ` marca o fim dessa sessão e desencadeia uma extração. O EverOS escreve então o episódio extraído em Markdown e incorpora-o de forma assíncrona no índice do Milvus.
Inspecionar a memória Markdown
O ficheiro de episódio gerado é armazenado nos âmbitos da aplicação, do projeto e do utilizador:
find "$EVEROS_ROOT/project-assistant/launch-planning/users/maya/episodes" \
-type f -name "*.md"
Saída de referência (a data no nome do ficheiro reflete o momento em que executa o exemplo):
everos-data/project-assistant/launch-planning/users/maya/episodes/episode-2026-09-08.md
Abra o ficheiro para ver as memórias extraídas pelo LLM. Um excerto resumido tem este aspeto:
## 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.
A formulação exata, os identificadores e os carimbos de data/hora podem variar, uma vez que a memória é extraída pelo LLM. Os ficheiros Markdown originais continuam a ser a fonte de verdade duradoura; o índice do Milvus pode ser reconstruído a partir deles.
Pesquisar as memórias
Utilize a pesquisa híbrida para determinar o que deve ser memorizado antes do Atlas entrar em funcionamento. Guarde o código seguinte como 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']}")
Execute a pesquisa:
uv run python search_memories.py
Resultado de referência (as pontuações e o texto podem variar):
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
Ambas as conversas do Atlas são apresentadas antes das oito conversas não relacionadas. O EverOS envia a consulta ao ponto final de incorporação da OpenAI, solicita ao Milvus candidatos BM25 e vetoriais dentro do âmbito da aplicação e do projeto da Maya e funde as duas listas de resultados.
Inspecione as coleções do Milvus
O EverOS cria uma coleção para cada tipo de memória derivada suportada. Utilize MilvusClient para listar o número de linhas de cada uma:
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()
Saída de referência da execução validada:
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
O número exato de factos atómicos pode variar consoante a saída do LLM. As dez linhas de episódios correspondem às dez conversas descarregadas. As outras coleções estão disponíveis para os modos de memória e funcionalidades do EverOS que este exemplo específico não utiliza.
Utilizar outra implementação do Milvus
Para utilizar outro ponto de extremidade do Milvus Server ou a Zilliz Cloud, atualize EVEROS_MILVUS__URI. Defina EVEROS_MILVUS__TOKEN quando o ponto de extremidade exigir autenticação. O código de ingestão e pesquisa permanece inalterado.
Conclusão
Ao combinar o EverOS com o Milvus, pode transformar conversas em memórias duradouras e recuperá-las através de palavras-chave e sinais semânticos. Pode adaptar o mesmo padrão para dotar assistentes e outras aplicações agentivas de memória de longo prazo para os seus próprios utilizadores, projetos e fluxos de trabalho.
