<div align="center">
<img src="https://raw.githubusercontent.com/RohiRIK/OpenLtm/HEAD/assets/openltm-banner.jpeg" alt="OpenLTM — Long-Term Memory for AI coding agents, now open source" width="820" />
OpenLTM
인증 계층(auth layer)에 대해 설명했는데, 왜 Claude가 내일 또 물어볼까요?
AI 코딩 에이전트를 위한 장기 메모리 (Long-Term Memory for AI coding agents) — Claude Code, OpenCode, Pi, OpenClaw, 그리고 Hermes
Version
License
Runtime
Database
Claude Code
MCP
모든 세션, 모든 업데이트, 모든 압축(compaction)을 거쳐 살아남는 영구적인 의미론적 메모리입니다.
</div>
이제 오픈 소스 (Now open source)
OpenLTM은 원래 하나의 에이전트를 위한 사설 메모리 계층으로 시작했습니다. 현재 MIT 라이선스가 적용되었으며, 전체 엔진은 사용자의 디스크에 있어 읽고, 포크(fork)하고, 해체할 수 있습니다.
- 하나의 엔진, 다섯 개의 호스트.
@rohirik/openltm-core가 메모리 로직을 담당하며; 각 호스트는 얇은 어댑터만 받습니다 (Hermes는 동일한 데이터베이스를 사용하는 네이티브 Python 플러그인 형태).
- 파일의 소유권이 사용자에게 있습니다. 로컬 SQLite 데이터베이스입니다. 계정, 대시보드, 또는 공급업체(vendor)에 의존하지 않습니다.
- 모든 것이 해킹 가능합니다. 훅(Hooks), 스킬(Skills), 청소부 제공자(janitor providers), 그래프 시각화기(graph visualizer). 이 모든 것이 공개되어 있습니다.
이전 설치 버전에서 마이그레이션하십니까? 마켓플레이스는 이제 RohiRIK/OpenLtm이며 플러그인은 openltm입니다. 기존 메모리 데이터베이스가 가져와집니다.
무언가를 저장하기 전에 이것을 읽으세요 (Read this before you store anything)
데이터베이스는 로컬입니다. 임베딩(Embeddings)과 청소부 LLM은 기본적으로 로컬에서 작동합니다.
의미론적 검색에는 벡터가 필요합니다. 기본 임베딩 제공자는 OpenAI와 호환되는 POST /v1/embeddings 엔드포인트를 통해, 로컬 llama.cpp 서버(llama-server --embeddings)를 이용한 bge-m3 모델입니다. 만약 해당 서버가 실행되고 있지 않다면, 검색(recall)은 FTS5에 머무릅니다 — 메모리 텍스트는 어딘가로 전송되지 않습니다. 클라우드 임베딩 제공자는 선택적 옵션만 가능합니다. 설정 (Configuration)을 참조하세요.
Janitor LLM은 기본적으로 로컬 Ollama를 사용합니다 (LTM_LLM_PROVIDER가 설정되지 않은 경우 → ollama). 클라우드 LLM 제공업체는 옵트인(opt-in) 방식이며, 메모리 콘텐츠는 해당 서비스를 고정(pin)할 때만 받습니다.
어떤 구성에서도 원격 측정(telemetry)이나 분석 기능은 없습니다.
llama-server -m bge-m3.gguf --embeddings --pooling mean --port 8080
...
백그라운드에서 서버 실행을 포함하여 5분 만에 설정할 수 있습니다: 로컬 임베딩 (Local embeddings). /openltm:doctor 명령어를 사용하면 시맨틱 리콜(semantic recall)이 실제로 활성화되었는지 확인할 수 있습니다.
어떤 쓰기 경로가 비밀 정보를 제거하는지, 어떤 경로가 그렇지 않은지에 대한 전체 세부 정보는 보안 참고 사항 (Security notes)을 참조하세요.
철학 (The philosophy)
메모리는 자동적이어야 합니다. 후크(Hooks)가 작업을 수행합니다. 세션 종료 후크(session-end hook)는 패턴을 추출하고, 세션 시작 후크(session-start hook)는 이를 다시 주입합니다. 기억하려고 노력할 필요가 없어야 합니다.
감쇠(Decay)는 버그가 아닌 기능입니다. 6개월 전의 문제로, 더 이상 다루지 않은 문제는 아마도 적용되지 않을 것입니다. importance: 5로 설정하면 메모리가 절대 만료되지 않습니다. 그 외 모든 것은 얼마나 확신했는지와 그것이 실제로 참임을 증명한 빈도에 따라 감쇠합니다 (janitor/decay.ts).
키워드보다 시맨틱(Semantic)입니다. FTS5 풀텍스트 검색과 벡터 검색은 병렬로 실행되며 Reciprocal Rank Fusion을 통해 융합됩니다. 의미로 검색합니다 — 예를 들어, “비동기 오류를 처리하는 방법”이라는 검색어는 해당 단어를 작성한 적이 없더라도 메모리를 찾아냅니다.
데이터의 주인이 되세요. 사용자의 디스크에 있는 파일입니다. 프로젝트를 떠날 때, 그 프로젝트가 배운 모든 것도 함께 사라집니다.
설계 철학 (Design ethos)
- 로컬 우선(Local-first). 데이터는 기기에 보관됩니다. 클라우드 계정이 필요하지 않습니다.
- 단일 SQLite 파일. 필수적인 그래프 데이터베이스(graph database), 워커 데몬(worker daemon) 또는 Docker 스택이 없습니다.
- 선별되고 지속 가능한 메모리(memories). 전체 세션 기록 보관본이 아니라 결정 사항, 선호도 및 관례를 저장합니다.
- 메모리는 시간이 지남에 따라 변화합니다. 노후화(Decay), 대체(supersede), 청소기 정리(janitor cleanup) 기능은 축적량보다 품질을 우선시합니다.
- 다중 호스트(Multi-host). Claude Code, OpenCode, Pi, Hermes, OpenClaw 등 다른 도구들도 동일한 데이터베이스를 통해 훅(hooks)과 어댑터(adapters)로 연결됩니다.
- 선택적 업그레이드. 그래프 서버 탐색기(graph-server explorer)와 Honker 확장 기능은 필요할 때 사용할 수 있으며, 필수 요구 사항이 아닙니다.
얻게 되는 것 (What you get)
| 기능 (Capability) | 실제 작동 방식 (What it actually does) | 위치 (Where it lives) |
|---|
| 검색(Recall) | 하이브리드 방식: 전체 텍스트 검색(full-text, FTS5) 및 벡터 결과가 상호 순위 융합(Reciprocal Rank Fusion)과 결합되며, 프로젝트, 상태 및 개인 정보 보호 수준으로 필터링됩니다. 정확한 단어가 아닌 의미로 검색합니다. | openltm-core/src/db.ts:981 · openltm-core/src/vec/ |
| ... | | |
다섯 개의 호스트, 하나의 데이터베이스
엔진은 하나의 패키지입니다. 각 호스트는 어댑터(adapter)를 받으며, 모두 동일한 openltm.db 파일을 엽니다. 따라서 Claude Code에서 학습된 정보가 OpenCode를 열 때 이미 존재합니다.
| 호스트 (Host) | 어댑터 (Adapter) | 설치 (Install) |
|---|
| Claude Code | .claude-plugin/ | claude plugin install openltm |
| ... | | |
Hermes는 어댑터 대신 네이티브 Python 플러그인을 사용합니다. 이는 동일한 데이터베이스와 동일한 스키마(schema)를 기반으로 하는 별도의 구현체입니다.
어디서 얻을 수 있나요 (Where to get it)
| 채널 (Channel) | 배포되는 내용 (What ships there) | 링크 (Link) | 업데이트 (Updates) |
| :--- | :--- | :--- |
| Claude Code (자체 마켓플레이스) | openltm 플러그인 | OpenLTM marketplace repository — Anthropic의 공식 디렉토리가 아닙니다 | 저장소 기반 (repository-backed) |
| ... |
The Hermes Plugin Catalog는 sha 687934564e68878ff9646a57aa72f6d3fc4f5fc8의 2.16.2에 고정(pinned)되어 있습니다 (merged PR #132746). 카탈로그 설치가 무엇을 받게 할지는 최신 저장소 태그가 아니라, 카탈로그의 정확한 커밋 고정(commit pin)에 의해 결정됩니다.
각 채널이 어떻게 게시되는지, 그리고 하나가 고장 났을 때 무엇을 해야 하는지에 대한 내용은 다음 문서를 참조하세요: docs/11-publishing.md.
설치 (Install)
마켓플레이스 (Claude Code에 권장)
한 단계만 진행하면 됩니다 (Claude Code 2.1.275 이상 버전):
claude plugin install openltm --marketplace RohiRIK/OpenLtm
또는 세션에서 다음 명령어를 사용하세요: /plugin install openltm --marketplace RohiRIK/OpenLtm. 이전 버전에서는 먼저 마켓플레이스를 추가해야 합니다:
claude plugin marketplace add https://github.com/RohiRIK/OpenLtm
claude plugin install openltm
Claude Code를 재시작합니다. 7개의 후크가 자동으로 연결되고, 7개의 명령어가 로드되며, 4개의 스킬과 2개의 에이전트가 활성화되고, openltm.db가 마이그레이션되거나 생성됩니다.
bunx (클론 불필요)
bunx @rohirik/openltm-core
bunx @rohirik/openltm-core --pi
bunx @rohirik/openltm-core --dry-run --claude
Hermes
hermes plugins install openltm
hermes config set memory.provider openltm
hermes gateway restart
Hermes Plugin Catalog에 고정된 검토된 커밋을 설치합니다. 상세 내용은: docs/10-hermes-plugin.md.
OpenClaw
openclaw plugins install clawhub:@rohirik/openclaw-ltm --accept-capabilities
openclaw plugins install @rohirik/openclaw-ltm --force --accept-capabilities
OpenClaw >= 2026.9.6, Node 24 (호스트 자체 요구 사항), 그리고 PATH에 Bun이 필요합니다. --accept-capabilities는 플러그인이 메모리 도구를 등록하는 것에 동의함을 의미하며, --force는 OpenClaw가 npm 설치가 ClawHub 검토 범위를 벗어났음을 인지하도록 하는 방법입니다 (OpenClaw 2026.9.8에서 확인됨). 상세 내용은: packages/adapter-openclaw/README.md.
개발용 / git 클론
git clone https://github.com/RohiRIK/OpenLtm ~/Projects/OpenLtm
cd ~/Projects/OpenLtm && bash install.sh
이 설치 프로그램이 저장소 외부에서 수행하는 작업에 대해 설명합니다. 이는 ~/.claude.json 파일을 작성하고, 존재하지 않으면 ~/.claude/settings.json을 생성하며, 메모리 도구가 더 이상 승인을 요청하지 않도록 mcp__plugin_openltm_memory를 permissions.allow 목록에 추가합니다. 이것은 에이전트의 도구 권한(tool permissions)을 의도적으로 확장하는 것이며, 설치 프로그램이 알려줘야 할 종류의 사항입니다. 실행하기 전에 먼저 scripts/install-wiring.ts를 읽어보고 싶다면 해당 파일을 참조하세요.
빠른 시작 (Quick start)
새 세션을 시작합니다. 컨텍스트는 자동으로 상단에 주입됩니다.
/openltm:memory recall auth — 이 프로젝트에서 auth에 대해 무엇을 알고 있나요?
/openltm:memory learn <insight> — 보관할 만한 무언가를 저장하세요
/openltm:health — 메모리 상태 및 감쇠 요약
...
헤드리스 에이전트용 (For headless agents)
슬래시 명령어와 ltm_* 도구는 에이전트 TUI(Text User Interface) 내부에서만 존재합니다. 일반 셸(plain shell)—스크립트, cron, CI 환경에서는 다음과 같이 사용합니다:
bunx @rohirik/openltm-core memory learn --text "Docker Hub rate limits unauthenticated pulls" \
--category gotcha --importance 4 --project homelab --json
bunx @rohirik/openltm-core memory recall --query "docker rate limit" --json
...
그래프 서버 없이 관리하기 (Curate without graph-server)
janitor(임베드 백필 → 감쇠 → 아카이브 → 승격 → 제안 중복 제거)는 SQLite 파일에 직접 실행됩니다. 그래프 서버나 Honker가 필요하지 않습니다:
bunx @rohirik/openltm-core janitor run
bunx @rohirik/openltm-core janitor status
bunx @rohirik/openltm-core janitor schedule --write
Claude Code 플러그인도 이를 SessionEnd 시점에, 6시간에 한 번 실행합니다. 다른 후크 호스트는 ltm hook --name SessionEnd를 호출할 수 있습니다. 자세한 내용, 설치 및 제거 단계: docs/13-janitor.md.
MCP를 지원하는 모든 호스트에서 전체 서버를 직접 실행할 수 있습니다:
bunx @rohirik/openltm-core mcp-serve
보안 주의사항 (Security notes)
이 시스템에 중요한 내용을 저장하기 전에 알아야 할 세 가지 사항입니다.
모든 쓰기 경로에 대해 비밀 정보 제거(Secret scrubbing)가 적용되는 것은 아닙니다. learn() 함수는 저장하기 전에 비밀 정보를 제거합니다 (packages/openltm-core/src/db.ts:561). janitor의 promote 및 dedup 경로는 그리고 컨텍스트 캡처는 이를 거치지 않고 memories와 context_items에 쓰기 작업을 수행합니다. 또한, 스크러버는 개방형(fail open)으로 작동하여 내부 오류가 발생하면 원본 텍스트를 변경 없이 반환하며 (secretsScrubber.ts:101), 이는 패턴 금지 목록(pattern denylist)일 뿐 보장이 아닙니다. 저장된 메모리는 마스킹된 메모리와 같지 않습니다.
LTM_SQLITE_LIB와 LTM_HONKER_EXT는 네이티브 코드를 로드합니다. 둘 다 SQLite 확장 로더에 전달되는 파일 시스템 경로입니다 (extensions.ts:132,144). 허용 목록(allowlist)이나 서명 확인 절차가 없습니다. 신뢰하는 경로로만 설정하거나, LTM_DISABLE_VEC=1 및 LTM_DISABLE_HONKER=1을 사용하여 로더를 비활성화하십시오.
npm 퍼블리싱은 토큰이 필요하지 않습니다. 릴리스는 출처 증명(provenance)과 함께 GitHub OIDC 신뢰 퍼블리싱을 통해 인증됩니다. 이 저장소에는 NPM_TOKEN이 저장되어 있지 않습니다.
더 깊이 알아보기 (Go deeper)
환경 변수 (Environment variables)
| 변수명 | 용도 |
|---|
LTM_DB_PATH | SQLite 파일이 위치하는 곳입니다. 기본 위치를 덮어씁니다. |
| ... | |
라이선스 (License)
MIT — RohiRIK
<div align="center">
잊는 에이전트를 위해, 그리고 잊어서는 안 되는 에이전트를 위해 제작되었습니다.
</div>
