← Docs hub

A2A Memory DB and Sync Contract

이 문서는 A2A 메모리 기능을 실제 구현으로 옮기기 위한 DB schema, sync cursor, privacy/delete 정책을 정의한다.

현재 구현 상태는 세션/voice_context 중심이다. 이 문서는 그 위에 장기 메모리를 얹기 위한 설계 기준이며, 아직 제품 DB 구현 완료를 의미하지 않는다.

1. 설계 목표와 제약

목표:

• 최소 단위는 user/assistant pair로 관리한다.
• session은 최대 8 pair를 묶지만, 항상 8 pair가 찬다고 가정하지 않는다.
• 하루 단기, 일주일 중기, 장기 profile memory를 분리한다.
• Planner는 memory를 참고하지만 현재 발화를 우선한다.
• 장기 memory는 candidate와 confirmed state를 분리한다.

제약:

• 온디바이스는 로컬 세션과 최근 turn cache를 관리한다.
• Cloud는 요약, 장기 후보 추출, profile 확정을 관리한다.
• 민감 정보는 저장 전 분류와 삭제 정책이 필요하다.
• 네트워크 단절 시 on-device local cursor가 재동기화 기준이 된다.

2. 아키텍처 개요

On-device local store
  conversation_pairs
  conversation_sessions
  active_workflow_cache
  sync_cursor

Cloud Memory DB
  short_term_summaries
  mid_term_summaries
  long_term_profile_candidates
  long_term_profile_items
  memory_audit_log

Planner Input
  recognized_text
  voice_context.recent_turns
  memory_snapshot.session_summary
  memory_snapshot.short_term
  memory_snapshot.mid_term
  memory_snapshot.profile_hints
  device_context

3. 컴포넌트 경계와 책임

3.1 현재 구현 상태

현재 repo에서 실제 구현되어 있는 부분은 DB가 아니라 runtime contract다.

현재 구현되지 않은 부분:

따라서 현재 memory는 “Planner에 안전하게 전달되는 context layer + 응답에 포함되는 write 후보” 단계로 보는 것이 정확하다.

4. 데이터 모델/저장소 전략

4.0 저장소 구현 단위

v1 구현은 아래 repository/worker 단위로 나누는 것이 좋다.

Worker는 repository 위에서 동작한다.

4.1 conversation_pairs

최소 대화 원자다.

4.2 conversation_sessions

최대 8 pair를 묶는 단기 흐름 단위다.

4.3 short_term_summaries

하루 단위 최근 맥락이다.

4.4 mid_term_summaries

일주일 단위 반복 주제와 최근 패턴이다.

4.5 long_term_profile_candidates

장기 profile 후보이며, 바로 확정하지 않는다.

4.6 long_term_profile_items

확정된 장기 memory다.

4.7 memory_sync_cursors

온디바이스와 Cloud 동기화 위치다.

4.8 memory_audit_log

memory 변경 이력이다.

5. API 계약 및 시퀀스

5.1 Runtime read path

Cloud Planner는 DB 전체를 직접 읽지 않고, runtime이 조립한 compact snapshot만 받는다.

request arrives
-> normalize_voice_context
-> hydrate_memory_context
-> memory_context injected into voice_context
-> planner prompt input

현재 구현 근거:

5.2 Runtime write path

Turn 종료 후에는 실제 DB write가 아니라 write candidate를 먼저 만든다.

route result / session_state
-> build_memory_update
-> write_candidates.short_term_pair
-> repository write 또는 on-device cache update
-> summarizer/promotion worker

현재 build_memory_update가 만드는 최소 형태:

{
  "contract_version": "a2a-memory-context-v1",
  "source": "cloud_a2a_runtime",
  "sync": {
    "cursor": "cur-2",
    "version": "v2"
  },
  "write_candidates": {
    "short_term_pair": {
      "user_text": "나는 거실을 자주 청정해",
      "assistant_text": "",
      "route_family": "DEF",
      "workflow_id": ""
    },
    "profile_candidates": []
  },
  "device_cache_update": {
    "active_workflow_id": "",
    "last_route": "DEF",
    "session_summary": ""
  }
}

후속 구현에서는 assistant_text, planner_summary, device_task_result, task_event_summary, sensitive_flags를 채워야 한다.

현재 write candidate를 DB에 연결할 때의 최소 mapping:

5.3 On-device -> Cloud request

{
  "recognized_text": "안방으로 가서 청정해줘",
  "voice_context": {
    "session_id": "session-123",
    "recent_turns": [],
    "history_hint_strength": "weak",
    "active_workflow_id": ""
  },
  "memory_snapshot": {
    "session_summary": "오늘 사용자는 청정 관련 요청을 여러 번 했다.",
    "short_term": [],
    "mid_term": [],
    "profile_hints": []
  },
  "memory_sync": {
    "device_cursor": "pair_seq_42",
    "last_cloud_update_seq": 18
  }
}

5.4 Cloud -> On-device response

{
  "session_state": {
    "session_id": "session-123",
    "workflow_context": {}
  },
  "memory_update": {
    "cloud_update_seq": 19,
    "session_summary_delta": "안방 청정 요청이 진행 중이다.",
    "profile_candidates": [
      {
        "candidate_id": "cand-001",
        "category": "device_pattern",
        "claim": "사용자는 안방 청정을 자주 요청한다.",
        "confidence": 0.62,
        "status": "pending"
      }
    ]
  }
}

5.5 Sync API 방향

On-device와 Cloud는 항상 같은 시점에 완벽히 동기화된다고 가정하면 안 된다.

동기화 원칙:

• 같은 pair가 두 번 업로드되어도 idempotent해야 한다.
• device_cursor가 뒤처지면 Cloud는 missing range 또는 conflict를 반환한다.
• Cloud가 내려주는 profile hint는 on-device local cache에 compact copy로만 유지한다.
• 삭제 요청은 Cloud DB와 on-device cache 양쪽에 반영되어야 한다.

6. Planner 사용 원칙

Planner는 memory를 아래 우선순위로 사용한다.

1. 현재 recognized_text.
2. active workflow / pending follow-up.
3. recent_turns.
4. session_summary.
5. short-term / mid-term summary.
6. confirmed long-term profile hints.

금지:

• memory preference가 현재 발화의 명확한 route family를 덮어쓰면 안 된다.
• long-term candidate를 confirmed profile처럼 쓰면 안 된다.
• 민감 정보나 삭제 요청된 memory를 prompt에 넣으면 안 된다.

7. Memory 충돌/오염 방지 규칙

Memory는 도움이 되지만 잘못 쓰면 planner를 오염시킨다.

8. Retention / Privacy 기본값 후보

제품 정책 확정 전까지는 아래를 기본 후보로 둔다.

민감정보 후보:

9. 구현 단계

| 단계 | 작업 | 검증 | |---|---| | M0 | 현재 runtime contract 고정 | test/test_memory_context.py 유지, schema fixture 추가 | | M1 | pair/session repository | append/read/session-close unit test | | M2 | sync cursor repository | duplicate/conflict/retry test | | M3 | short-term/day summarizer | session -> day summary fixture | | M4 | mid-term/week summarizer | day summaries -> weekly digest fixture | | M5 | profile candidate extractor | repeated pattern -> pending candidate | | M6 | promotion gate | pending -> confirmed/rejected/expired | | M7 | privacy/delete worker | delete/mask/audit integration test | | M8 | planner integration | memory_context가 prompt에 들어가지만 current utterance를 덮지 않는 regression |

10. 비기능 요구 대응

11. 리스크와 의사결정 로그

12. 구현 전 결정 필요

관련 페이지

• Memory and Personalization
• Planner and Routing
• Requirements Traceability Matrix
• A2A Next Action Board