memini

AI 에이전트를 위한 공유적이고 영속적인 메모리 서비스.

memini는 MCP 기능을 갖춘 모든 에이전트(Claude Code, Cursor, Codex, opencode, Hermes, OpenClaw, Open WebUI)에게 기억하고 회상할 수 있는 단일 장소를 제공하며, 시간이 지남에 따라 검색 품질이 복리처럼 증가합니다. 이는 단일 Go 바이너리로 실행되며, 설정 없이 부팅되고, 노트북의 임베디드 SQLite 파일부터 Kubernetes의 Postgres까지 확장됩니다.

문서화 (Documentation)

작동 방식 (How it works)

memini는 세 가지 이전 프로젝트의 장점을 결합했습니다:

• 청크(chunk)들의 무더기가 아닌, 선별되고 중복이 제거된 아티팩트 (Karpathy의 "LLM wiki" 이후).
• 감쇠 및 하이브리드 검색(벡터 + 키워드)을 갖춘 계층적 메모리(작업 기억, 일화 기억, 의미 기억, 절차 기억)와 Reciprocal Rank Fusion (agentmemory 이후). 각 계층이 무엇을 의미하는지 그리고 메모리가 어떻게 이동하는지에 대한 내용은 docs/tiers.md를 참조하세요.
• 옵션으로 LLM 통합 파이프라인, 메모리별 TTL(Time To Live), 네임스페이스별 격리, Prometheus 메트릭, 그리고 fsck 일관성 검사기(mnemory 이후)를 갖춘 상태 비저장(stateless)의 K8s 네이티브 HTTP 서비스.

h이브리드 검색 결과는 단순히 유사도만을 기준으로 하는 것이 아니라, 관련성, 접근 최신성, 중요도의 복합 지표로 재순위화되며, 거의 동일한 중복 항목은 회상 시점에 병합됩니다.

LLM은 선택 사항입니다. LLM을 구성하면 쓰기 작업이 즉시 저장되고 백그라운드에서 중복 제거 및 모순 해결 과정을 거칩니다. 또한, 새로운 에피소드 기록(episodic capture)은 쓰기 시점에 영속적인 의미론적 사실(semantic facts)로 정제되므로, 한 번 진술된 사실은 즉시 영속성을 갖습니다. LLM 없이도 마커 휴리스틱(marker heuristics)은 동일한 생명주기를 거치므로, 임베더 전용 배포 환경에서도 영속적인 지식(durable knowledge)이 계속 축적됩니다.

빠른 시작 (Quick start)

memini는 임베디드 SQLite 모드에서 별도의 설정 없이 부팅됩니다. 벡터 검색(Vector search)은 자체적으로 만들 수 없는 기능이므로, OpenAI와 호환되는 임베딩 엔드포인트 중 아무 곳에나 연결하면 됩니다:

export MEMINI_EMBED_BASE_URL=http://localhost:8081/v1
export MEMINI_EMBED_MODEL=bge-m3
export MEMINI_EMBED_DIMS=1024   # 모델과 일치해야 함
... 

MEMINI_EMBED_DIMS는 연결하는 모델의 차원(dimension)과 일치해야 합니다. 이것이 가장 흔한 설정 실수이며, 깨끗하게 실패하기보다는 스토어를 손상시킵니다.

에이전트에 통합하는 것을 포함하여 전체 과정을 보려면 Solo laptop을 참조하십시오. Docker, Compose 및 Kubernetes의 경우 Deployment를 참조하십시오.

에이전트 플러그인 (Agent plugin)

대부분의 통합(integration)은 서버 주소로 **MEMINI_BASE_URL**을, 토큰으로 **MEMINI_API_KEY**를 읽습니다. MEMINI_URL과 MEMINI_TOKEN은 제거되었으며, 클라이언트는 세션 시작 시 한 번 경고 메시지를 표시하고 그 외에는 무시합니다. Codex 및 Cursor 플러그인은 예외입니다: 이들의 내장된 MCP 설정은 고정된 로컬 URL과 정적 환경 변수 기반 헤더를 사용하므로, 아래의 원격 재정의(remote override) 방법을 참조하십시오. 통합에 자체 구성(opencode 옵션, Open WebUI Valves, openclaw.json)이 있는 경우, 해당 구성이 환경 변수를 덮어씁니다.

Claude Code:

opencode에 플러그인을 추가하려면 opencode.json (또는 ~/.config/opencode/opencode.json)을 수정하세요:

{
  "plugin": ["@eleboucher/opencode-memini"]
}

Hermes: hermes plugins install eleboucher/memini-hermes

OpenClaw: openclaw plugins install clawhub:@eleboucher/memini

Open WebUI: Admin Panel의 Functions에 filter/memini_memory.py를 붙여넣고, 선택적으로 Workspace의 Tools에 tools/memini_tools.py를 붙여넣으세요.

Codex:

codex plugin marketplace add eleboucher/memini
codex plugin add memini@memini

먼저 로컬 서버를 시작하고 (memini, 기본값 http://localhost:8080), 인증이 활성화된 경우 MEMINI_API_KEY를 설정한 다음, /hooks로 번들된 훅을 검토하고 신뢰한 후 새 스레드를 시작하세요. 원격 및 커스텀 서버 설정은 integrations/codex/에서 다룹니다.

Cursor:

ln -s "$PWD/plugin" ~/.cursor/plugins/local/memini

창을 새로고침(Developer: Reload Window)하고 Customize → Plugins에서 확인한 다음, 팀의 경우 리포를 마켓플레이스로 가져오는 것이 좋습니다 (Dashboard → Plugins → Import from Repo). 번들된 MCP 서버는 고정된 http://localhost:8080/mcp를 대상으로 하며, 인증 및 원격 설정(a ~/.cursor/mcp.json 오버라이드)은 plugin/README.md에서 다룹니다.

전체 세부 정보, 엣지 케이스 및 모든 클라이언트 측 설정은 integrations/와 plugin/README.md에 있습니다. 변수가 효과가 없는 것처럼 보이면 서버 대 클라이언트 변수를 확인하세요: 네 개의 이름이 각각 다른 의미를 가집니다.

MCP 서버로 사용하기

memini는 두 가지 전송 계층을 통해 Model Context Protocol (MCP)을 지원합니다:

• 원격 (스트리밍 HTTP): http://<host>:8080/mcp
• 로컬 (stdio): memini mcp

에이전트가 볼 수 있는 9가지 도구와 해당 매개변수, 그리고 서버가 연결되는 모든 클라이언트에게 보내는 기본 정책은 MCP tools에서 확인할 수 있습니다. 바로 붙여넣을 수 있는 클라이언트 설정 파일들은 integrations/에 있습니다.

벤치마크 (Benchmarks)

memini의 하이브리드 검색(hybrid retrieval)은 동일한 모델, 데이터셋 및 지표에서 agentmemory가 발표한 LongMemEval-S 수치를 능가합니다 (recall@5 기준 98.4% 대 95.2%). 또한, 재순위 지정(reranking) 기능은 기본 recall이 여전히 개선 여지가 있는 턴 레벨 세트에서 두 자릿수 향상을 더해줍니다.

mise run bench

전체 표, 개별 단계 및 카테고리별 분석, 튜닝 및 제외된 분할(held-out split), 매개변수 탐색(parameter sweeps), 방법론, 주의사항, 그리고 mem0 및 Letta 대비 LoCoMo 비교는 bench/README.md에 있습니다.

기여 (Contributing)

개발 루프(dev loop), 생성된 코드 드리프트 게이트(generated-code drift gates), 문서화 규칙은 CONTRIBUTING.md를 참고하세요. 간단히 말해, docs/reference/ 아래의 참조 문서는 코드(mise run docs)로부터 생성되며, 만약 이 내용이 변경되었다면 CI가 실패합니다. 설정(setting), CLI 명령어 또는 MCP 도구를 추가하는 경우, mise run docs를 실행하고 그 결과를 커밋하세요. 새로운 설정에 문서 주석(doc comment)이 없거나 어떤 섹션에도 속하지 않는 경우 생성기가 작동을 거부하는데, 이는 의도된 동작입니다. 이렇게 해야만 '문서화되지 않은' 노브가 배포될 수 있습니다.

라이선스 (License)

AGPL-3.0.