Genesys

AI 메모리를 위한 지능 계층.

AI 에이전트 메모리를 위한 점수 엔진 + 인과 그래프 + 수명 주기 관리자. MCP를 기본적으로 지원합니다.

소개

Genesys는 AI 메모리를 위한 점수 엔진, 인과 그래프, 수명 주기 관리자입니다. 메모리는 곱셈 공식(관련성 × 연결성 × 재활성화)으로 점수가 매겨지고, 인과 그래프로 연결되며, 관련성이 없어지면 능동적으로 삭제됩니다. 모든 스토리지 백엔드에 연결할 수 있으며 MCP를 기본적으로 지원합니다.

Related MCP server: tentra

필요성

• 평면적 메모리는 확장되지 않습니다. 모든 것을 벡터 저장소에 덤프하면 이해 없이 회상만 가능합니다. 500번째 메모리가 중요한 5개를 묻어버립니다.

• 망각이 없으면 지능도 없습니다. 실제 메모리 시스템은 망각합니다. 능동적인 정리 없이는 AI가 오래된 컨텍스트에 잠기게 됩니다.

• 인과적 추론이 없습니다. 벡터 유사성은 "왜 X를 선택했는가?"라는 질문에 답할 수 없습니다. 그래프가 필요합니다.

당신의 AI는 모든 것을 기억하지만 아무것도 이해하지 못합니다. Genesys가 이를 해결합니다.

빠른 시작

대부분의 사용자는 옵션 1(인메모리)로 시작하는 것이 좋습니다. API 키 없이 완전히 로컬에서 사용하려면 옵션 3: Obsidian + 로컬로 이동하세요.

옵션 1: 인메모리 (의존성 없음)

Genesys를 가장 빠르게 체험하는 방법입니다. 데이터베이스가 필요 없으며, 상태는 메모리에 유지되고 선택적으로 JSON 파일에 저장됩니다.

pip install genesys-memory
cp .env.example .env
# Set OPENAI_API_KEY in .env

uvicorn genesys.api:app --port 8000

재시작 후에도 유지하려면 .env에 GENESYS_PERSIST_PATH를 설정하세요:

GENESYS_PERSIST_PATH=.genesys_state.json

Claude에게 설정을 요청하세요: *"genesys-memory를 설치하고, OpenAI 키가 포함된 .env 파일을 생성하고, 인메모리 백엔드로 8000번 포트에서 서버를 시작한 뒤, MCP 서버로 연결해줘."

옵션 2: Postgres + pgvector (프로덕션)

pgvector를 통한 벡터 검색으로 지속적이고 확장 가능한 스토리지를 제공합니다.

pip install 'genesys-memory[postgres]'
cp .env.example .env

.env 편집:

OPENAI_API_KEY=sk-...
GENESYS_BACKEND=postgres
DATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys

Postgres 시작 및 마이그레이션 실행:

docker compose up -d postgres
alembic upgrade head
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000

Claude에게 설정을 요청하세요: *"genesys-memory[postgres]를 설치하고, docker compose를 사용하여 pgvector가 포함된 Postgres 컨테이너를 시작하고, alembic 마이그레이션을 실행하고, OpenAI 키와 DATABASE_URL이 포함된 .env 파일을 생성하고, GENESYS_BACKEND=postgres로 서버를 시작한 뒤, MCP 서버로 연결해줘."

옵션 3: Obsidian Vault (로컬 우선)

Obsidian 볼트를 Genesys 메모리 저장소로 변환합니다. 마크다운 파일은 메모리 노드가 되고, [[wikilinks]]는 인과적 에지가 됩니다. SQLite 사이드카(.genesys/index.db)가 인덱싱을 처리합니다.

pip install 'genesys-memory[obsidian]'
cp .env.example .env

.env 편집:

OPENAI_API_KEY=sk-...
GENESYS_BACKEND=obsidian
OBSIDIAN_VAULT_PATH=/path/to/your/vault

서버 시작:

uvicorn genesys.api:app --port 8000

처음 시작할 때 Genesys는 볼트 내의 모든 .md 파일을 인덱싱하고 임베딩을 생성합니다. 파일 감시자가 노트를 편집할 때마다 점진적으로 다시 인덱싱합니다.

OBSIDIAN_VAULT_PATH가 설정되지 않은 경우, Genesys는 ~/Documents/personal, ~/Documents/Obsidian, ~/obsidian에서 .obsidian/을 찾아 자동으로 감지합니다.

완전 로컬 (API 키 없음)

로컬 임베딩 제공자를 사용하여 외부 의존성 없이 Obsidian 모드를 실행하세요:

pip install 'genesys-memory[obsidian,local]'

GENESYS_BACKEND=obsidian
GENESYS_EMBEDDER=local
OBSIDIAN_VAULT_PATH=/path/to/your/vault
# No OPENAI_API_KEY needed

uvicorn genesys.api:app --port 8000

이 방식은 임베딩을 위해 sentence-transformers를 통해 all-MiniLM-L6-v2(384차원)를 사용합니다. 모델은 처음 사용할 때 다운로드됩니다(~80MB).

Claude Desktop 연결 — claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "genesys": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

또는 Claude Code의 경우:

claude mcp add --transport http genesys http://localhost:8000/mcp

Claude에게 설정을 요청하세요: *"genesys-memory[obsidian,local]을 설치하고, GENESYS_BACKEND=obsidian, GENESYS_EMBEDDER=local, OBSIDIAN_VAULT_PATH=[YOUR_VAULT_PATH]로 설정된 .env 파일을 생성하고, 8000번 포트에서 서버를 시작한 뒤, MCP 서버로 연결해줘. API 키는 필요 없어."

옵션 4: FalkorDB (그래프 네이티브)

네이티브 그래프 탐색을 위해 FalkorDB(Redis 기반 그래프 데이터베이스)를 사용합니다.

pip install 'genesys-memory[falkordb]'
cp .env.example .env

.env 편집:

OPENAI_API_KEY=sk-...
GENESYS_BACKEND=falkordb
FALKORDB_HOST=localhost

FalkorDB 및 서버 시작:

docker compose up -d falkordb
uvicorn genesys.api:app --port 8000

Claude에게 설정을 요청하세요: *"genesys-memory[falkordb]를 설치하고, docker compose를 사용하여 FalkorDB 컨테이너를 시작하고, OpenAI 키와 GENESYS_BACKEND=falkordb가 포함된 .env 파일을 생성하고, 8000번 포트에서 서버를 시작한 뒤, MCP 서버로 연결해줘."

소스에서 설치

git clone https://github.com/rishimeka/genesys.git
cd genesys
pip install -e '.[dev]'

시드 스크립트

두 개의 유틸리티 스크립트가 REST API를 통해 실행 중인 Genesys 인스턴스에 데모 데이터를 채웁니다. Clerk 인증이 구성된 실행 중인 서버가 필요합니다.

cp .env.example .env
# Set CLERK_SECRET_KEY and CLERK_USER_ID in .env

python seed_demo.py      # Creates 25 memories with causal edges and runs recall queries
python seed_recalls.py   # Runs 5 rounds of recall queries to build reactivation history

두 스크립트 모두 환경 변수(.env를 통해)에서 자격 증명을 읽습니다. 필요한 모든 변수는 .env.example을 참조하세요.

AI에 연결

Claude Code

claude mcp add --transport http genesys http://localhost:8000/mcp

Claude Desktop

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "genesys": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

모든 MCP 클라이언트

클라이언트를 MCP 엔드포인트로 지정하세요:

http://localhost:8000/mcp

MCP 도구

작동 원리

모든 메모리는 세 가지 힘을 곱한 값으로 점수가 매겨집니다:

decay_score = relevance × connectivity × reactivation

• **관련성(Relevance)**은 시간이 지남에 따라 감소합니다. 오래된 메모리는 강화되지 않으면 사라집니다.

• **연결성(Connectivity)**은 많은 인과적 링크를 가진 메모리에 보상을 줍니다. 허브 메모리는 살아남습니다.

• **재활성화(Reactivation)**는 계속해서 회상되는 메모리를 강화합니다. 빈도가 중요합니다.

공식이 곱셈 방식이므로, 메모리가 살아남으려면 세 가지 축 모두에서 점수를 얻어야 합니다. 연결성은 높지만 접근하지 않는 메모리는 여전히 감쇠합니다. 자주 회상되지만 인과적으로 고립된 메모리도 여전히 사라집니다.

STORE → ACTIVE → DORMANT → FADING → PRUNED
           ↑                    │
           └── reactivation ────┘
                                  (only if score=0, orphan, not pinned)

메모리는 핵심(core) 상태로 승격될 수 있습니다. 이는 구조적으로 중요한 메모리로, 자동으로 고정되며 절대 삭제되지 않습니다.

벤치마크 결과

LoCoMo 장기 대화 메모리 벤치마크에서 테스트됨 (10개 대화에 걸친 1,540개의 질문, 카테고리 5 제외 — 정답에 사실 오류가 포함된 적대적 질문, 예: 잘못된 날짜 및 이벤트 귀속):

답변 모델: gpt-4o-mini | 판정 모델: gpt-4o-mini | 검색 k=20

참고로, 동일한 벤치마크에서 Mem0은 67.1%, Zep은 75.1%를 기록했습니다. 전체 재현 스크립트는 benchmarks/에 있습니다.

스토리지 백엔드

구성

.env.example을 .env로 복사하고 설정하세요:

모든 옵션은 .env.example을 참조하세요.

제작자

Genesys는 Astrix Labs의 Rishi Meka가 제작했습니다. 매 세션마다 Claude에게 프로젝트 컨텍스트를 다시 설명해야 하는 좌절감에서 시작되었습니다. 목표는 LLM과 메모리 사이의 지능 계층을 만드는 것이며, 완전히 오픈 소스입니다.

기여

CONTRIBUTING.md를 참조하세요.

라이선스

AGPL-3.0-or-later

참고: v0.3.6 이전의 Genesys 릴리스는 실수로 Apache 2.0으로 문서화되었습니다. LICENSE 파일에는 항상 AGPLv3 텍스트가 포함되어 있었습니다. v0.3.6부터 모든 문서는 기여자 라이선스 계약(CLA)과 함께 AGPL-3.0-or-later를 올바르게 참조합니다.