mnemox-ai/tradememory-protocol

TradeMemory Protocol – AI 거래 에이전트를 위한 로컬 우선 메모리 및 안전 계층

정의 – AI 기반 트레이더가 수행하는 모든 거래를 기록하고, 트레이더 자신의 과거 성과를 분석하며, 다음 주문이 브로커의 MCP(Market-Connect-Protocol) 서버에 도달하기 전에 개입(거부 또는 재정렬)할 수 있는 오픈소스 Python 패키지입니다. 인기 있는 브로커 API(Alpaca, Hyperliquid, MT5, Binance)와 함께 작동하며, 사용자 정의 위험 정책을 적용하는 경량 프록시로 실행될 수 있습니다.

핵심 개념

• 회상 – recall_memories(order="losses_first")는 과거 손실 거래를 결과, 유사성, 최신성, 신뢰도 및 "감정 상태"(OWM 5요인 모델)에 따라 가중치를 두고 반환합니다.
• 기록 – remember_trade는 거래를 5개 메모리 계층(일화, 의미, 절차, 정서, 원시 기록)에 기록합니다.
• 반성 – 주기적인 통계 요약(중간 보유 시간, 손실 집중도, R-배수)은 에이전트가 드리프트를 감지하는 데 도움을 줍니다.
• 감사 – 모든 결정은 SHA-256 해시로 체인되고, 매일 Merkle 루트로 고정되어 변조 방지 로그를 제공하며 내보낼 수 있습니다.

사용 방법

1. 기록 동기화 – tradememory sync hyperliquid --address 0x… 또는 tradememory sync alpaca --env-file ~/.secrets/alpaca.env는 체결 내역을 로컬 SQLite DB로 가져옵니다.
2. 에이전트에 메모리 서버 추가 – Claude Desktop(또는 MCP 호환 에이전트)에서 tradememory MCP 서버를 구성합니다.
3. 사전 점검 – 에이전트가 주문을 제안하기 전에 recall_memories를 호출하여 유사한 과거 손실을 표시합니다. 프록시는 한도를 위반하는 주문을 자동으로 거부할 수 있습니다.
4. 선택적 브레이크 – proxy 추가 기능(pip install "tradememory-protocol[proxy]")을 설치하여 정책 승인 주문만 브로커에 전달하고 모든 결정을 기록하는 로컬 프록시를 실행합니다.

주요 기능 (MCP 도구)

카테고리	도구	목적
메모리	remember_trade, recall_memories	거래 기록, 가중 손실 우선 목록 검색
상태	get_agent_state, get_behavioral_analysis	현재 신뢰도, 하락폭, 연속 기록 지표
계획	create_trading_plan, check_active_plans	조건부 거래 계획 수립
위험	check_trade_legitimacy	5요인 사전 거래 게이트(전체 / 축소 / 건너뛰기)
감사	export_audit_trail, verify_audit_hash, verify_audit_chain	변조 방지 로깅, Merkle 루트
진화	evolution_* 도구	연구 등급 전략 생성 및 백테스팅

일반적인 사용 사례

• 미국 주식 트레이더 – 개인 사용자가 메모리 서버를 로컬에서 실행하고, 각 Alpaca 주문 전에 "손실 우선" 체크리스트를 받고, 일일 손실 한도를 적용합니다.
• Forex EA 시스템 – 자동화된 MT5 전문가 자문가가 거래를 동기화하고, 메모리 계층이 최근 손실 패턴을 반복하는 주문을 자동으로 거부합니다.
• 규정 준수 감사 추적 – 기관 사용자가 SHA-256 체인 로그를 내보내 MiFID II 또는 향후 EU AI 법안 요구 사항을 충족합니다.

제한 사항 (LIMITATIONS.md 참조)

• OWM 점수는 연구 등급이며, 통계적 유의성은 아직 수집 중입니다(현재 검증은 20건 미만 거래).
• 주문 유형의 일부(브래킷, 스톱-리밋, 트레일링)만 현재 거부되며 평가되지 않습니다.
• 감사 기록에 대한 기본 제공 디지털 서명이 없으며, 변조 방지는 해시 체인에 의존합니다.
• 진화 엔진은 실험적이며 프로덕션 배포용이 아닙니다.

설치 및 빠른 시작

pip install tradememory-protocol          # 코어 메모리 서버
tradememory sync hyperliquid --address 0xYourAddress
# 선택적 브레이크 프록시 (Python 3.12+)
pip install "tradememory-protocol[proxy]"
tradememory proxy init --account-id <id> --symbols AAPL,MSFT

tradememory를 MCP 서버로 실행하고 AI 에이전트의 MCP 구성을 해당 서버로 지정하십시오.

보안 및 개인정보 보호

• 메모리 서버는 브로커 키를 절대 보유하지 않습니다. 키는 프록시가 시작한 브로커 프로세스에만 전달됩니다.
• 모든 아웃바운드 호출은 읽기 전용입니다(선택적 Discord 웹훅은 MT5 동기화 제외).
• 감사 루트는 기본적으로 RFC 3161을 통해 타임스탬프가 적용되며, TRADEMEMORY_TSA=off로 비활성화할 수 있습니다.

연구 상태

• OWM 5요인 채점 구현 및 CI 테스트 완료.
• 감사 추적 완전 작동.
• 진화 및 하이브리드 벡터 회상은 연구 모드입니다.
• 지속적인 실증적 검증(통계적 신뢰를 위해 ≥100건 거래 목표).

문서 및 지원

• 시작 가이드, 사용 사례, API 참조, OWM 프레임워크, 아키텍처 및 중국어 README는 모두 docs/ 폴더에 있습니다.
• 이슈: brake-integration 이슈를 열거나 30분 무료 설정 상담을 예약하십시오.

라이선스 – 코어 패키지는 MIT; 선택적 proxy 추가 기능은 mnemox-control(AGPL-3.0 전용, 상용 라이선스 제공)을 포함합니다.

투자 조언이 아닙니다 – 이 도구는 과거 손실 패턴만 표시하며, 거래 결정은 사용자의 책임입니다.