agent-memory

로컬 장기 기억 인프라(Local Long-Term Memory Infrastructure). agent 중립적: 특정 agent 프레임워크에 바인딩되지 않으며, 세 가지 방식으로 접속한다——

• Python 라이브러리: LangGraph 등 프레임워크에서 직접 import agent_memory(참조 agent_memory/long_term/adapters/);

• MCP server: MCP를 지원하는 모든 클라이언트(참조 agent_memory/server/, M2+ 구현);

• Skill: Skill을 지원하는 agent에 Skill 형태로 마운트(참조 skills/agent-memory/, M3 구현).

접속 절차와 각 호스트 어댑터 지원 상황은 docs/agent-integration.md 참조(호스트 runtime 책임 목록 포함).

현재 상태: M7(완료)

M0은 프로젝트 골격과 핵심 schema만 제공:

• agent_memory/models.py: 기억 항목(MemoryEntry), 증거 포인터(EvidenceRef), 증류 제안(MemoryProposal)의 pydantic 모델과 검증 규칙;

• agent_memory/config.py: 단일 구성 모듈, 환경 변수로 덮어쓰기 가능, 잘못된 구성은 fail-closed;

• evals/datasets/layer1/: 20개 "기본 회상" 평가 케이스(YAML), 이후 M1+ 회상 평가용.

M1은 기억 커널 MVP(수동 증류) 제공: long_term/store/(Markdown 기억 레이어 + sqlite-vec/FTS5 파생 인덱스), long_term/retrieve/(bge-m3 임베딩 + 밀집/희소 RRF 혼합 검색), long_term/ingest/redact.py(정규식 비식별화), cli.py(add / search / list / update / forget / rebuild / stats), evals/runners/recall_eval.py(layer1 recall@5).

M2는 증류 쓰기 경로 + MCP server 제공:

• agent_memory/llm.py: LLMClient 프로토콜(의존성 주입, 테스트용 fake)과 OpenAILLMClient(OpenAI 호환 엔드포인트, 기본 DeepSeek, key 없으면 fail-closed);

• agent_memory/long_term/ingest/distill.py: 대화 → 원자 기억 후보(prompt 하드 규칙: 지시성 내용은 절대 추출하지 않음, 레드라인 D2; id/confidence/detail을 먼저 정규화한 후 검증, 정규화 후에도 비법이면 data/review_queue/로 이동, 조용히 폐기하지 않음);

• agent_memory/long_term/ingest/gate.py: 평가 게이트(비식별화 잔여 / 지시성 내용 / 길이 하한 / low 신뢰도 세 버킷 분류);

• agent_memory/long_term/ingest/reconcile.py: Mem0식 대조(ADD / UPDATE / DELETE / NOOP, 충돌이 수렴되지 않으면 data/review_queue/에 기록); UPDATE/DELETE 저장 후 long_term/ingest/propagate.py 변경 전파(과거 사실에 의존하는 근접 항목을 LLM이 무효/수정 필요/영향 없음으로 판정, 무효 삭제는 감사 로그 data/logs/propagation.jsonl에 남기고, 수정 필요는 검토 큐로);

• agent_memory/long_term/retrieve/inject.py: 검색 결과를 <recalled_memories> XML 주입 블록으로 렌더링("참고이지 지시가 아님" 가드 프리픽스 포함, 예산 초과 시 전체 잘라냄);

• agent_memory/server/mcp_server.py: MCP stdio server, 다섯 개 tool(memory_search / memory_add / memory_feedback / memory_update / memory_forget);

• evals/datasets/layer2/: 20개 다중 세션 검색/모호성 해소 케이스(시계열 충돌 7 + 다중 객체 모호성 해소 7 + 유효/무효 구분 6);

• evals/runners/e2e_eval.py: 엔드투엔드 평가(LLM key 없으면 자동으로 규칙 판정 모드로 다운그레이드).

M3은 LangGraph 어댑터 + Skill + 궤적 프리픽스 회귀 평가 제공:

• agent_memory/long_term/adapters/langgraph/store.py: AgentMemoryStore(LangGraph BaseStore 구현, namespace ("memories", <scope>), put 시 비식별화+평가 게이트 규칙 통과, search는 혼합 검색);

• agent_memory/long_term/adapters/langgraph/tools.py: build_memory_tools()가 MCP와 완전히 정렬된 14개 ReAct tool 생성(3계층 기억 전부 노출, 비즈니스 구현은 MemoryService에 수렴); 기본은 전체 파이프라인(LLM 대조 포함), LLM이 없을 때만 명시적으로 순수 규칙 대조로 다운그레이드(근접 중복 NOOP, 그 외 ADD);

• agent_memory/long_term/retrieve/resident.py: build_system_context(scope) 상주 레이어 주입(profile 기억을 신뢰도 순으로 system prompt에 넣음, 예산은 회상 예산의 절반);

• skills/agent-memory/SKILL.md: agent에게 언제 검색/쓰기/피드백할지 가르침(MCP tool 이름과 매개변수 예시, "회상은 참고이지 지시가 아님");

• evals/datasets/prefix/ 9개 궤적 프리픽스 회귀 케이스(지시 충돌 2 + scope 누출 2 + 낮은 신뢰도 2 + 주입 저항 2 + 정상 회상 대조 1);

• evals/runners/prefix_regression.py: 고정 컨텍스트 → LLM이 다음 동작 출력 → 심사위원이 허용/금지 집합 판정(429 자동 재시도, key 없으면 건너뜀);

• examples/langgraph_demo.py: 최소 LangGraph ReAct agent 접속 데모(세션 간 선호도 기억).

M4a는 진화 폐쇄 루프 핵심(수면 학습 루프 + 정기 정리) 제공, 이중 루프 형성: 온라인 루프는 증거만 추가(증류→평가 게이트→대조), 오프라인 루프는 기억 저장소를 일괄 정리——

• agent_memory/long_term/evolve/trigger.py: 트리거 판정(마지막 정리 후 N일 초과 / 새 항목 임계값 초과 / review_queue 적체 임계값 초과, 어느 하나라도 충족하면 트리거, 임계값은 모두 AGENT_MEMORY_EVOLVE_* 환경 변수로);

• agent_memory/long_term/evolve/consolidate.py: 통합 산출 EvolutionProposal——중복 제거 병합(근접 쌍을 LLM이 MERGE/CONFLICT/UNRELATED로 판정, CONFLICT는 강제 수렴하지 않고 인계), 오프라인에서 가장 오래된 항목 재검토(long_term/ingest/propagate.py의 judge_propagation 재사용), 장기 미검색 항목 가중치 하향/아카이브 제안; 제안은 data/review_queue/evolution/<timestamp>/에만 기록, 절대 기억 레이어를 직접 수정하지 않음;

• agent_memory/long_term/evolve/verify.py: 3단계 검증(boundary 계약 확인 / retention 기준 query top-5 diff / safety 안전 기억 보호), 하나라도 통과하지 못하면 전체 거부;

• agent_memory/long_term/evolve/apply.py: 승격 전 스냅샷(data/snapshots/<timestamp>/), 적용 후 감사(data/logs/evolution_audit.jsonl), rollback(snapshot_id) 롤백;

• agent_memory/long_term/evolve/cycle.py: 5단계 오케스트레이션(트리거 → 타겟팅 → 통합 → 검증 → 정리);

• models.py: MemoryEntry에 retrieval_count 필드 추가(hybrid 검색 적중 시 +1, 쓰기 경로 근접 검색은 미포함).

M4b는 layer3 평가 세트 + 진화 지표 + 실제 수용 제공:

• evals/datasets/layer3/: 12개 세션 간 숨은 연관 케이스(책 제3층 "능동 서비스"의 프로그래밍 시나리오 개조: 사실과 계획이 서로 다른 세션에 있고, 정답을 맞히려면 둘 사이의 숨은 충돌을 능동적으로 알려야 함; 각 케이스는 profile 상주 레이어 기억

  • 검색 레이어 세부 기억을 포함, rubric.essential에 반드시 "숨은 연관 능동 알림" 항목 포함);

• evals/runners/metrics.py: 쌍별 통계(McNemar 정확 검정 + 쌍별 bootstrap 이득 구간, 순수 함수로 scipy 의존성 없음, 표본 < 20이면 "강한 결론을 내리기에 부족" 명시);

• evals/runners/e2e_eval.py에 --baseline 추가: 같은 케이스 배치를 빈 저장소에서 쌍별 재실행, 문제별 승패, p값, 홀드아웃 이득 구간 출력; 세 가지 진화 지표 계측——활성화율(기억이 회상된 비율), 준수율(심사위원이 판정 근거가 회상 기억에서 왔음을 확인한 케이스 비율), 홀드아웃 이득(기억 있음 - baseline 점수 차이);

• 실제 수용 수치: layer3 기억 있음 91.67% vs baseline 0%(McNemar p=0.0010, n=12 방향성 참고만); 회귀 layer1 100% / layer2 100% / prefix 88.89%; evolve 폐쇄 루프 실제 데모(boundary 거부 1회와 merge 승격 + 롤백 1회 포함)로 consolidate 결함 2건 노출, AGENTS.md 미해결 문제 참조.

M5는 수동 검토 상호작용 노드 + 강제 업데이트 hook 제공:

• config.py에 review_gate 추가(off / ask / strict, 기본 ask: 검토 큐에 적체가 있으면 memory_search의 처리 등급)와 review_turn_interval(기본 3, hook의 라운드 간격), 환경 변수 AGENT_MEMORY_REVIEW_GATE / AGENT_MEMORY_REVIEW_TURN_INTERVAL로 덮어쓰기;

• MCP tool이 다섯 개에서 일곱 개로 확장——memory_review_list(대기 상세)와 memory_review_resolve(approve 원본 저장 / modify 텍스트 수정 후 비식별화+평가 게이트 통과 후 저장 / discard 폐기) 추가; memory_search에 검토 게이트 추가(ask 등급은 blocked 후 사용자 확인 후 통과, strict 등급은 무조건 거부, off는 차단 안 함); memory_add가 pending_review 대기 검토 상세 반환;

• 증류 prompt에 "사용자 확인 자격" 하드 규칙 추가: assistant가 일방적으로 제안하고 사용자가 명시적으로 확인하지 않은 제안/방안/결론은 침전하지 않음;

• scripts/memory_turn_hook.py: kimi-code Stop hook, session 기준 라운드 계산, N라운드마다 이번 라운드 종료를 가로채고 증류 지시 주입(재료 = 각 라운드 사용자 메시지 + 인접 assistant 응답), 사용자 레벨 ~/.kimi-code/config.toml에 등록됨.

M6은 HTTP 상주 서비스 + scope 규율 제공:

• agent_memory/server/http_server.py: streamable-http 상주 서비스, 기본 127.0.0.1:8765에만 바인딩 (루프백 주소는 자연스럽게 인증 불필요), MCP 엔드포인트 위에 /SKILL.md(프롬프트 레이어 전문 배포)와 /bootstrap (새 agent 접속 안내 지시) 두 개 정적 라우트 추가; 상대 agent는 안내 지시 하나로 접속 가능, 파일 복사 불필요;

• scope 규율(공용 라이브러리 하나, 다중 agent 다중 프로젝트 혼용): SKILL.md에 scope 선택 규칙 추가(공통은 global, 프로젝트는 repo:<이름>, 모르겠으면 먼저 사용자에게 질문), memory_add의 scope 기본값은 global로 폴백하지만 반환에 scope_reminder 알림 첨부;

• Windows 상주 운영: scripts/start_http_server.cmd 시작 래퍼 스크립트(크래시 시 자동 재시도 최대 3회, 3연패 시 data/state/http_server_FAILED.txt 실패 마커 작성 후 수동 처리, 로그는 data/logs/http_server.log)

  • 로그인 트리거 예약 작업(등록 스크립트 scripts/register_task_s4u.ps1, 관리자 권한 필요).

M7은 3계층 기억(장기 / 작업 / 단기) + 통합 인터페이스 제공:

• 패키지 구조 마이그레이션: 기존 store/ retrieve/ ingest/ evolve/ adapters/ 다섯 개 하위 패키지를 전체적으로 agent_memory/long_term/로 이동(로직 변경 없음), working/과 short_term/ 추가;

• agent_memory/working/: 작업 기억(운영 레이어, 현재 작업 상태——목표/할 일/결정/변수/메모, scope마다 하나씩, data/working/에 저장). 쓰기는 전체 교체, 비식별화만 통과하고 평가 게이트는 통과하지 않음; turn_watermark 워터마크와 stale_wm으로 상태 지연 여부 판정;

• agent_memory/short_term/: 단기 기억 transcript 어댑터 레이어, agent 네이티브 로그 (예: kimi-code의 wire.jsonl)를 깨끗한 라운드 시퀀스로 파싱, 새 파일 생성 없음;

• MCP tool이 일곱 개에서 열세 개로 확장: memory_wm_read / memory_wm_write / memory_wm_clear (작업 기억 읽기/쓰기/비우기), memory_context(상주 프로필 + 작업 기억 + 회상 한 번에 조립), memory_transcript_read(라운드 읽기, since_turn 증분), memory_session_end (세션 마무리: data/raw 아카이브 + 공동 증류 + 완료된 할 일 정리, pending 할 일은 veto).

Related MCP server: mnemo

디렉터리 구조

agent-memory/
├── agent_memory/     # Python 包（扁平布局，import 名 agent_memory）
│   ├── config.py         # 配置（AGENT_MEMORY_* 环境变量覆盖）
│   ├── models.py         # 记忆条目 schema（M0 核心）
│   ├── long_term/        # 长期记忆：store / ingest / retrieve / evolve / adapters（M1-M4，M7 迁入）
│   ├── working/          # 工作记忆：当前任务状态，操作层（M7a）
│   ├── short_term/       # 短期记忆：transcript 适配层（M7b）
│   └── server/           # MCP server：stdio（M2）+ HTTP 常驻（M6）
├── skills/agent-memory/  # Skill 接入方式（M3）
├── scripts/              # 运维脚本：turn hook（M5）、HTTP 服务启动/计划任务注册（M6）
├── evals/                # 评估集：datasets / rubrics / runners（agent 禁改，D6）
├── tests/
└── data/                 # 运行时数据（gitignored）：raw / memory / working / review_queue / snapshots / state / logs

빠른 시작

uv sync          # 创建虚拟环境并安装依赖
uv run pytest    # 跑测试
uv run ruff check .

M2 사용법

LLM 구성(증류 / 대조 / LLM 심사위원용)

증류 쓰기 경로는 OpenAI 호환 엔드포인트 필요, 기본 DeepSeek(https://api.deepseek.com, 모델 deepseek-chat):

export AGENT_MEMORY_LLM_API_KEY=sk-...
# 可选覆盖：AGENT_MEMORY_LLM_BASE_URL / AGENT_MEMORY_LLM_MODEL
# 评估评委可单独配置（异源互审）：AGENT_MEMORY_JUDGE_LLM_API_KEY 等

key를 구성하지 않으면 검색, 수동 쓰기, 피드백, 삭제 등 LLM에 의존하지 않는 기능은 정상 사용 가능; 대화 증류 경로만 호출 시 오류 발생(fail-closed).

CLI 증류 명령

대화 하나([{role, content}, ...]의 JSON 파일)를 전체 쓰기 파이프라인으로 저장:

uv run agent-memory distill --file conversation.json --scope repo:my-project \
    --source kimi-code --session-id 2026-08-19-session
# 管线：蒸馏 → 评价门 → 对账；无法自动收敛的冲突会写入 data/review_queue/

MCP server

시작: uv run python -m agent_memory.server.mcp_server(stdio).

Claude Code / Kimi Code의 MCP 구성 조각:

{
  "mcpServers": {
    "agent-memory": {
      "command": "uv",
      "args": ["run", "python", "-m", "agent_memory.server.mcp_server"],
      "env": {
        "AGENT_MEMORY_DATA_DIR": "C:/Users/<you>/.agent-memory/data",
        "AGENT_MEMORY_LLM_API_KEY": "sk-...",
        "AGENT_MEMORY_LLM_BASE_URL": "https://api.deepseek.com",
        "AGENT_MEMORY_LLM_MODEL": "deepseek-chat"
      }
    }
  }
}

다섯 개 tool로 시작(M5부터 일곱 개로 확장, M7부터 열세 개로 확장, 아래 M5 / M7 사용법 참조): memory_search(혼합 검색 + XML 주입 블록, scope 필터는 서버 측에서 강제), memory_add(대화 JSON은 증류 파이프라인 / 단일 content는 비식별화+대조), memory_feedback(신뢰도 상향/하향, low 미만으로 내려가면 검토 큐로), memory_update(비식별화+평가 게이트 통과 후 업데이트), memory_forget(삭제).

엔드투엔드 평가

uv run python evals/runners/e2e_eval.py --layers 1,2            # 无 key 时自动规则降级模式
uv run python evals/runners/e2e_eval.py --layers 1,2 --llm-judge # 真实 LLM 评委按 rubric 判定
uv run python evals/runners/e2e_eval.py --layers 3 --llm-judge --jobs 8   # layer3 跨会话隐藏关联
uv run python evals/runners/e2e_eval.py --layers 3 --llm-judge --jobs 8 --baseline
    # --baseline：同一批用例在空库下配对重跑，输出逐题胜负 / McNemar p 值 /
    # 配对 bootstrap 留出增益区间，以及激活率 / 遵循率 / 留出增益三个进化指标
uv run python evals/runners/e2e_eval.py --layers 2 --llm-judge --jobs 8   # 调高用例并发
uv run python evals/runners/e2e_eval.py --layers 2 --llm-judge --no-cache # 禁用响应缓存

속도 향상 메커니즘(실제 모드 기본 적용):

• LLM 응답 디스크 캐시: 증류 / 대조 / 심사위원의 각 응답을 sha256(model + system + user)로 data/logs/llm_cache/에 캐시(gitignored). 재실행 시 변경되지 않은 부분은 캐시 직접 적중, 초 단위 완료; 모델 변경 시 자동 미적중. --no-cache로 끄기.

• 케이스 레벨 동시성: --jobs N(기본 4)으로 스레드 풀에서 케이스 동시 실행, 각 케이스는 독립 임시 디렉터리, 429 속도 제한 시 자동 지수 백오프 재시도.

• 모델 로딩: bge-m3는 프로세스당 한 번 로드(약 1-2분). 여러 layer를 실행할 때는 --layers 1,2로 한 번에 실행, 두 프로세스로 각각 한 layer씩 실행하지 말 것.

규칙 다운그레이드 모드는 실제 증류 품질을 의미하지 않으므로, 공식 수용은 실제 LLM 구성 후 재실행 필요.

M3 사용법

LangGraph 접속

직접 작성한 LangGraph agent는 세 가지 접속 방법이 있으며, 중첩 사용 가능:

from agent_memory.long_term.adapters.langgraph.store import AgentMemoryStore
from agent_memory.long_term.adapters.langgraph.tools import build_memory_tools
from agent_memory.long_term.retrieve.resident import build_system_context
from langgraph.prebuilt import create_react_agent

# 1) BaseStore：namespace 约定 ("memories", <scope>)，put/search/delete 直接映射到记忆内核
store = AgentMemoryStore()          # 配置走 AGENT_MEMORY_* 环境变量
store.put(("memories", "repo:myproj"), "db-choice",
          {"content": "本项目数据库定为 SQLite，文件 data/app.db。", "confidence": "high"})

# 2) ReAct tool：recall_memories / save_memory 挂进 tools 列表
tools = build_memory_tools()

# 3) 常驻层：profile 类记忆渲染进 system prompt（预算是召回预算的一半）
prompt = "你是用户的编程助手……\n\n" + build_system_context("repo:myproj")

agent = create_react_agent(model, tools, prompt=prompt, store=store)

완전한 실행 가능 예시는 examples/langgraph_demo.py 참조(uv run python examples/langgraph_demo.py, AGENT_MEMORY_LLM_API_KEY 필요).

BaseStore의 put은 저수준 동기 인터페이스: 호출자가 정제된 원자 내용을 제공해야 하며, 어댑터 레이어는 비식별화+평가 게이트 규칙(지시성 내용은 직접 오류 발생)을 통과하지만 LLM 증류는 하지 않음; save_memory tool의 대조는 LLM 없는 순수 규칙 경로(근접 중복 NOOP, 그 외 ADD), 충돌 수렴은 여전히 M2 증류 파이프라인 사용.

Skill 접속

skills/agent-memory/SKILL.md는 프롬프트 레이어로, 캡슐화된 agent(Kimi Code / Claude Code)에게 언제 검색, 쓰기, 피드백할지 가르침. 설치 방법(MCP server와 함께 사용):

• Kimi Code: skills/agent-memory/를 ~/.kimi-code/skills/agent-memory/로 복사 또는 심볼릭 링크;

• Claude Code: ~/.claude/skills/agent-memory/로 복사;

• 동시에 위 MCP 구성대로 agent-memory server를 마운트해야 Skill의 tool 이름(memory_search 등)에 구현이 생김.

궤적 프리픽스 회귀 평가

고정 컨텍스트(system + 주입된 기억 블록 + 사용자 최신 메시지) → LLM이 다음 동작 출력 → 심사위원이 허용 집합에 속하고 금지 집합에 닿지 않았는지 판정. 네 가지 경계 시나리오(지시 충돌 / scope 누출 / 낮은 신뢰도 / 주입 저항) + 정상 회상 대조 포함:

uv run python evals/runners/prefix_regression.py             # 需 LLM key，无 key 整体跳过
uv run python evals/runners/prefix_regression.py --seeds 3   # 多种子报均值与区间
uv run python evals/runners/prefix_regression.py --no-cache  # 禁用 LLM 响应缓存（默认开）

429 속도 제한은 자동 간격 재시도; LLM 응답 디스크 캐시는 e2e_eval과 data/logs/llm_cache/ 공유. 이 평가는 규칙 다운그레이드 모드 없음(actor 동작 자체가 피측정 대상).

M4 사용법

수면 학습 루프(evolve)

# dry-run：只到提案为止，打印提案摘要，不验证、不应用
uv run agent-memory evolve --dry-run

# 完整循环：触发 → 整合 → 三档验证 → 通过则晋升（自动快照 + 审计）
uv run agent-memory evolve

# 只整理某个 scope
uv run agent-memory evolve --scope repo:my-repo

트리거 조건(어느 하나라도 충족, 임계값은 AGENT_MEMORY_EVOLVE_* 환경 변수로 덮어쓰기): 마지막 정리 후 7일 초과(EVOLVE_INTERVAL_DAYS), 새 항목 50개 초과(EVOLVE_NEW_ENTRIES_THRESHOLD), 검토 큐 적체 10개 초과(EVOLVE_REVIEW_BACKLOG_THRESHOLD).

정리 산출물은 제안(data/review_queue/evolution/<timestamp>/proposal.yaml)이며, 직접 개정이 아님: 3단계 검증(boundary / retention / safety) 중 하나라도 통과하지 못하면 거부, 제안은 보관 후 수동 처리; 모두 통과해야 승격——승격 전 기억 레이어 스냅샷(data/snapshots/<timestamp>/), 승격 후 감사 로그(data/logs/evolution_audit.jsonl). 롤백은 agent_memory.long_term.evolve.apply.rollback(snapshot_id, settings, embedder)로 스냅샷에서 기억 레이어 복원 후 인덱스 재구축.

M5 사용법

수동 검토(검토 큐의 두 상호작용 노드)

증류 불법 산출물, 평가 게이트의 낮은 신뢰도 판정, 대조 수렴 불가 충돌은 모두 data/review_queue/로 들어가 수동 판정 대기. 검토는 두 MCP tool로 완료:

• memory_review_list: 대기 상세 목록(출처, 이유, 내용);

• memory_review_resolve: 판정——approve 원본 저장 / modify 텍스트 수정 후 비식별화+평가 게이트 통과 후 저장 / discard 폐기. 판정 성공 시 큐 파일 삭제; raw_record류 대기는 직접 저장 불가.

검토 게이트(AGENT_MEMORY_REVIEW_GATE, 기본 ask): 큐에 적체가 있을 때 memory_search의 동작—— ask는 status=blocked 반환 후 사용자 확인(acknowledge_pending=true 통과) 대기, strict는 무조건 거부 (무인 시나리오용), off는 차단 안 함. memory_add의 반환에 pending_review 상세 첨부, agent는 항목별로 사용자에게 보고하고 판정 요청(SKILL.md에 해당 절차 있음).

강제 기억 업데이트 hook

scripts/memory_turn_hook.py는 kimi-code의 Stop hook: session 기준 라운드 계산, 매 AGENT_MEMORY_REVIEW_TURN_INTERVAL(기본 3) 라운드마다 세션 종료를 한 번 가로채고 증류 지시 주입 (재료 = 각 라운드 사용자 메시지 + 인접 assistant 응답). 사용자 레벨 ~/.kimi-code/config.toml에 등록되어 모든 프로젝트 세션에 적용; 다른 호스트는 스크립트를 참조해 직접 연결.

M6 사용법

HTTP 상주 서비스

stdio 모드는 호스트가 server를 자식 프로세스로 띄워 세션과 함께 생성/소멸; HTTP 모드는 장기 실행 로컬 서비스로, HTTP 요청을 보낼 수 있는 모든 agent 호스트는 URL 하나를 등록하면 열세 개 tool 전부 획득:

uv run python -m agent_memory.server.http_server
# 默认监听 http://127.0.0.1:8765/mcp（只绑回环地址，天然免鉴权）
# 覆盖：AGENT_MEMORY_HTTP_HOST / AGENT_MEMORY_HTTP_PORT

서비스에 정적 라우트 두 개 추가: /SKILL.md(프롬프트 레이어 전문)와 /bootstrap(접속 안내 지시). 새 agent 접속은 /bootstrap의 내용만 주면 됨: http://127.0.0.1:8765/mcp 등록 (전송 유형 streamable-http) + /SKILL.md 읽고 준수, 파일 복사 불필요.

Windows 상주(예약 작업)

scripts/start_http_server.cmd는 시작 래퍼 스크립트: 비정상 종료 시 60초 대기 후 재기동, 최대 3회; 3연패 시 data/state/http_server_FAILED.txt 실패 마커 작성 후 수동 처리; 로그는 data/logs/http_server.log. scripts/register_task_s4u.ps1은 로그인 트리거 예약 작업 등록 (S4U 백그라운드 모드, 완전 무창), 관리자 권한 필요. 두 스크립트 모두 순수 ASCII 유지 필수 (cmd.exe는 .cmd를 GBK로 읽고, PowerShell 5.1은 BOM 없는 .ps1을 ANSI로 읽음, 비 ASCII는 파싱 손상).

M7 사용법

통합 컨텍스트 조립과 작업 기억

memory_context(scope, query?, k?, current_turn?)가 한 번에 세 섹션 조립: 상주 프로필 블록(장기 기억의 profile) → 작업 기억 블록(현재 작업 상태) → 회상 블록(query 전달 시에만 장기 기억 검색). 현재 작업 상태 일상 유지는 세 개 작업 기억 tool 사용:

• memory_wm_write(scope, goal?, decisions?, variables?, todos?, notes?, turn_watermark?): 전체 교체 쓰기(병합 아님, 전달하지 않은 필드는 비워짐), 비식별화만 통과, 평가 게이트는 통과하지 않음;

• memory_wm_read(scope, current_turn?): 읽기 + 신선도 판정(stale_wm=true는 현재 라운드 수가 작업 기억의 turn_watermark 워터마크를 초과했음을 의미——"이 상태가 몇 라운드까지 업데이트됐는지", 상태가 지연됐을 수 있음);

• memory_wm_clear(scope): 비우기(멱등, 원래 없어도 오류 아님).

작업 기억은 운영 레이어 초안: 완료 항목의 결론은 장기 기억으로 증류(memory_add 또는 아래 memory_session_end) 해야 침전됨.

세션 로그 읽기와 세션 마무리

memory_transcript_read(log_path, adapter?, since_turn?)가 agent 세션 로그(예: kimi-code의 wire.jsonl, 파일 이름으로 형식 자동 인식)를 깨끗한 라운드 시퀀스(user/assistant/tool)로 파싱; since_turn 과 작업 기억 워터마크로 증분 읽기(워터마크 이후 라운드만 반환).

memory_session_end(scope, conversation_json?|log_path?, ...)는 세션 종료의 표준 마무리로 한 번에 완료: 원문 아카이브(data/raw/, 추가만 하고 개정 없음) → 공동 증류(대화 + 작업 기억 스냅샷을 참조 컨텍스트로) → 작업 기억에서 완료된 할 일 정리. 작업 기억에 pending 할 일이 남아 있으면 veto(아카이브/증류/정리 모두 실행 안 함), 종료 확정 시 force=true 전달. N라운드마다의 롤링 증류 hook과 이중 트랙 분업: hook은 중간 크래시 손실 방지 보험, session_end 는 표준 마무리.

세 가지 아키텍처 레드라인

AGENTS.md 참조. 요약: 데이터 3계층 분리(raw는 추가만, memory는 유일한 사실 소스, index는 재구축 가능하고 절대 수동 수정 금지); 쓰기는 반드시 비식별화→증류→대조 게이트 통과; evals / rubric / 릴리스 게이트 / 감사 로그는 agent가 임의 수정 금지.