KTCrisis/flux7-memory

flux7-memory은(는) 무엇을 하나요?

AI 에이전트를 위한 관리형 멀티 에이전트 메모리 — 마크다운+SQLite 하이브리드, FTS, 벡터 검색, LLM 재순위화. 단일 Go 바이너리, MCP stdio + HTTP + SSE.

개요

flux7-memory는 AI 에이전트에게 지속적이고 검색 가능한 메모리를 제공하는 경량 고성능 서버입니다. 여러 에이전트가 공유하거나 격리된 메모리 공간에서 작업할 수 있도록 지원하며, 정책 기반 접근 제어를 통해 데이터 거버넌스를 강화합니다.

주요 기능

• 하이브리드 저장소: 마크다운 파일과 SQLite 데이터베이스를 결합하여 구조화된 데이터와 비구조화된 텍스트를 모두 저장
• 전문 검색(FTS): SQLite FTS5를 사용한 빠른 키워드 검색
• 벡터 검색: 임베딩 기반 유사도 검색으로 의미적 관련성 파악
• LLM 재순위화: 검색 결과를 LLM으로 재평가하여 최적의 컨텍스트 제공
• MCP 지원: Model Context Protocol을 통해 모든 MCP 호환 에이전트와 통합
• 다중 프로토콜: stdio, HTTP, SSE(Server-Sent Events) 지원
• 거버넌스: 메모리 접근 정책, 감사 로그, 역할 기반 제어
• 단일 바이너리: Go로 작성되어 별도의 의존성 없이 실행 가능

설치

사전 요구 사항

• Go 1.21 이상 (빌드 시)
• SQLite (라이브러리 포함)

빠른 시작

go install github.com/KTCrisis/flux7-memory/cmd/flux7-memory@latest

또는 직접 빌드:

git clone https://github.com/KTCrisis/flux7-memory.git
cd flux7-memory
make build

사용법

MCP 서버 실행

STDIO 모드

export MEMORY_PATH=./memory
export MEMORY_GOVERNANCE_POLICY=./policy.yaml
flux7-memory --mcp-stdio

HTTP 모드

flux7-memory --mcp-http --port 8080

SSE 모드

flux7-memory --mcp-sse --port 8081

에이전트 통합 예제 (Claude Code)

claude_code_config.yaml 파일에 다음을 추가:

mcp_servers:
  flux7-memory:
    command: flux7-memory
    args: ["--mcp-stdio"]
    env:
      MEMORY_PATH: /path/to/memory
      MEMORY_GOVERNANCE_POLICY: /path/to/policy.yaml

환경 변수

변수명	설명	기본값
MEMORY_PATH	메모리 저장소 경로	./flux7-memory
MEMORY_GOVERNANCE_POLICY	거버넌스 정책 파일 경로	./policy.yaml
MEMORY_VECTOR_DIMENSION	벡터 차원	1536
MEMORY_FTS_ENABLED	FTS 활성화	true
MEMORY_RERANK_ENABLED	LLM 재순위화 활성화	true
MEMORY_RERANK_MODEL	재순위화에 사용할 LLM 모델	gpt-4o-mini
MEMORY_LOG_LEVEL	로그 레벨	info

정책 파일 예제 (policy.yaml)

agents:
  - name: "agent-alpha"
    allowed_actions: ["read", "write", "delete"]
    memory_scopes: ["project-alpha", "shared"]
  - name: "agent-beta"
    allowed_actions: ["read"]
    memory_scopes: ["shared"]

audit:
  enabled: true
  log_path: ./audit.log

API 참조

MCP Tools

도구 이름	설명
memory_store	키-값 쌍으로 메모리 저장
memory_retrieve	키로 메모리 검색
memory_search	FTS 또는 벡터 검색 수행
memory_delete	메모리 항목 삭제
memory_list	모든 메모리 항목 나열
memory_purge	특정 에이전트의 모든 메모리 삭제

MCP Resources

리소스 URI	설명
memory://{agent}/{key}	특정 메모리 항목 접근
memory://{agent}	에이전트의 모든 메모리
memory://system/stats	시스템 통계

라이선스

MIT License

기여

기여는 언제나 환영합니다! 버그 리포트, 기능 제안, 풀 리퀘스트를 보내주세요.