Seahorse

LLM 에이전트를 위한 영속적이고 이중 시간(bi-temporal) 메모리 — 로컬 우선(local-first), MCP 네이티브, Obsidian에서 읽을 수 있는.

pip install seahorse-memory
seahorse init myvault && seahorse remember "Sergio lives in Madrid"
seahorse recall "where does Sergio live?"

왜인가

LLM 에이전트는 매 세션을 0부터 시작한다. 컨텍스트 윈도우는 메모리가 아니다. 그것은 초기화되는 스크래치패드이며, 에이전트가 몇 주간의 작업을 통해 배운 것을 담기에는 너무 작다. 이 문제를 해결하려는 도구들은 나름의 문제를 가지고 있다:

• 에이전트는 심하게 잊는다. 대부분의 메모리 시스템은 사실을 무한정 축적할 뿐 모순을 해결하지 않는다 — 에이전트는 사용자가 마드리드와 바르셀로나에 동시에 산다고 "기억"하지만, 어느 것이 최신인지 알 방법이 없다.

• 불투명하다. 메모리는 사람이 읽거나, 수정하거나, 감사할 수 없는 독점 데이터베이스에 저장된다. 에이전트가 틀리면 그것을 바로잡을 방법이 없다.

• 주입 비용이 비싸다. 모든 에피소드가 LLM을 통과하므로, 작은 사실 수천 개를 기록하는 것도 실제 돈이 든다.

• 종속을 강요한다. 메모리 시스템을 도입하면, 그 시스템의 런타임이나 공급사, 생태계까지 함께 도입하게 되는 경우가 많다.

• 벤치마크를 신뢰할 수 없다. 이 분야의 수치 자체가 재현하기 어렵다. LOCOMO 벤치마크는 gold 정답의 6.4%가 틀렸고, Mem0는 재현이 깨져 있으며(이슈 #2800), MTEB 임베딩 점수는 메모리 검색 성능을 예측하지 못한다(LMEB, arXiv 2603.12572).

Seahorse는 다른 접근이다: 에이전트가 쓰고 읽고, 사람이 읽고 교정할 수 있고, 어떤 런타임이나 공급자에도 종속되지 않는 개방적이고 이식 가능한 이중 시간(bi-temporal) 메모리 표준.

Related MCP server: agentcairn

대상

• 에이전트를 만드는 개발자 — (Claude Code, Cursor, Codex 또는 직접 만든 에이전트) 에이전트가 세션을 넘어서 결정과 컨텍스트를 기억하기를 원하는 사람.

• Obsidian 파워 유저 — 노트가 단순한 정적 아카이브에 그치지 않고, 에이전트가 질의하고 유지 관리하는 지식 기반이 되기를 원하는 사람.

• 이식 가능한 메모리를 원하는 팀 — 이력을 다시 재생하지 않고도 공급자 사이를 옮길 수 있는 포맷을 원하는 팀.

사용 사례: 지속 메모리를 갖춘 Claude Code

Seahorse를 가장 빨리 확인할 수 있는 방법은 Claude Code에 세션 사이에서도 유지되는 메모리를 주는 것이다. 세 단계:

1. 세션 캡처. seahorse setup가 observer 훅을 ~/.claude/settings.json에 설치하고, seahorse observe start가 캡처 워커를 실행한다. 모든 세션은 에피소드로 기록된다 — skip-first(비용이 거의 0), 민감 정보가 제거된(redacted), 결정론적 요약이 포함된다.

seahorse setup
seahorse observe start

2. 세션 간 회상. SessionStart 훅이 seahorse context를 다음 세션에 주입하므로, 에이전트는 이전에 배운 내용을 시작점으로 가동된다. seahorse recall로 직접 물어볼 수도 있다:

seahorse context
seahorse recall "what did we decide about the API design?"

3. 기존의 메모리를 가져오기. 이미 claude-mem을 사용하고 있다면, seahorse import가 그 관찰들을 표준 에피소드로 마이그레이션한다 — 재생(replay)도, 잠금(lock-in)도 없다:

seahorse import --mode commit

핵심 차이는: 에이전트가 당신이 Obsidian에서 편집하는 바로 그 볼트(vault)에 기록한다는 것이다. 모든 에피소드는 YAML frontmatter가 있는 마크다운 파일이다 — 사람이 읽을 수 있고, 편집 가능하고, git에서 diff할 수 있고, 감사할 수 있다. 에이전트의 기억은 블랙박스가 아니라 당신의 노트이다.

에이전트에서 사용하기 (MCP)

Seahorse는 에이전트를 위해 설계되었다. 메모리 표면은 MCP를 포함하는 어떤 에이전트든 연결할 수 있는 stdio MCP 서버(io.seahorse.memory/v1)이다. CLI는 사람과 셸 스크립트를 위한 것이고, 에이전트는 seahorse-mcp와 통신한다.

Claude Code에 서버 등록 (로컬 범위, 기본값):

claude mcp add seahorse-mcp -- uvx --from seahorse-memory seahorse-mcp --vault "${HOME}/myvault"

--는 필수다 — Claude 자체 플래그와 서버 명령을 분리한다. 팀와 공유하려면 .mcp.json(git에 체크인된)을 통해 --scope project를 사용하라. claude mcp list(에 ✔ Connected가 보인다)와 claude mcp get seahorse-mcp로 검증한다.

또는 프로젝트 루트에 .mcp.json을 설정 (모든 MCP 클라이언트와 동작):

{
  "mcpServers": {
    "seahorse-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "seahorse-memory", "seahorse-mcp", "--vault", "${HOME}/myvault"]
    }
  }
}

참고: .mcp.json에서는 ~이 확장되어 있지 않다. — ${HOME} 또는 절대 경로 사용. (settings.json에 있는 mcpServers는 조용히 무시된다. MCP 서버는 user/local 범위의 경우 ~/.claude.json에, 프로젝트 범위의 경우 .mcp.json에 있다.)

연결되면 에이전트는 14개의 메모리 도구를 볼 수 있다. — remember, recall, recall_timeline, recall_full, improve, forget, build_pit, skill_add, skill_show, skill_list, skill_search, freshness_view, audit_log, follow_supersedes_chain (에이전트 표면( The agent surface 참조).

observer(seahorse setup)은 별도의 구성 요소다. — Claude Code 세션을 에피소드로 캡처한다. MCP 서버는 에이전트가 메모리를 읽고 쓰는 방식이다. 둘은 함께 동작한다 — 세션을 캡처하고, 그다음 그것들을 가로질러 회상하는 것이다.

작동 방식

graph LR
    A[Claude Code / any MCP agent] -- stdio MCP io.seahorse.memory/v1 --> S[seahorse-mcp]
    S --> E[Bi-temporal engine]
    E --> DB[(sqlite3 + sqlite-vec + FTS5)]
    E --> V[Obsidian vault: markdown + F3.1 frontmatter]
    H[Human in Obsidian] --> V

에이전트는 stdio MCP를 통해 seahorse-mcp와 대화한다. 엔진은 모든 에피소드를 두 군데 저장한다. 한 번은 단일 파일 SQLite 데이터베이스(벡터 검색을 위한 sqlite-vec, 전체 텍스트용 FTS5), 그리고 볼트에는 F3.1 frontmatter가 있는 마크다운 파일로 저장한다. 사람이 같은 마크다운을 편집한다. 형식은 버전물이 적용되고 docs/f3.1-format.md에 문서화되어 있다.

빠른 시작

# Install (PyPI):
pip install seahorse-memory
# …or with uv:
uv tool install seahorse-memory
# For hybrid semantic retrieval (FastEmbed ONNX, downloads mE5-small on first
# embed): pip install "seahorse-memory[embeddings]"
# For the multi-LLM extraction path (LiteLLM): pip install "seahorse-memory[llm]"

# Create a vault and write your first episode:
seahorse init myvault
seahorse remember "Sergio lives in Madrid" --title home
seahorse recall "madrid"

# Improve and forget (append-only; history is preserved):
seahorse improve <ep_id> "Sergio lives in Barcelona" --reason correction
seahorse forget <ep_id> --reason done

# Session capture, context, and consolidation:
# Install the observer (writes [observe] + merges the Claude Code hooks into
# ~/.claude/settings.json):
seahorse setup
# Start the observer (unix socket + worker), then the next session is captured
# automatically (skip-first, redacted, deterministic summary):
seahorse observe start
seahorse observe status
# Bootstrap context by recency (the SessionStart hook injects this):
seahorse context
# Distill recurrent episodes into semantic knowledge notes (N≥3, idempotent):
seahorse consolidate
# Remove the observer:
seahorse setup --uninstall

# Serve an agent over stdio MCP (io.seahorse.memory/v1):
seahorse-mcp --vault myvault
# …equivalently:
seahorse mcp --vault myvault

seahorse 콘솔 스크립트는 사람과 셸 스크립트용이고, seahorse-mcp는 에이전트용이다. seahorse mcp 하위 명령은 seahorse-mcp와 동일한 stdio 서버를 호출하므로, 두 에이전트 진입점은 동등하다. 에이전트를 연결하려면, Using from agent를 참조한다.

사전 조건

• Python ≥ 3.11 (최근 3.11/3.12/3.13 모두 동작한다). 인터프리터의 sqlite3가 enable_load_extension을 지원해야 한다(sqlite-vec에 필요). 표준 빌드의 대부분은 지원하며, 지원하지 않으면 seahorse doctor가 FAIL로 보고한다.

• Obsidian은 선택 사항이다. Seahorse는 어떤 마크다운 디렉터리에서도 동작한다 — seahorse init은 일반 폴더에 .seahorse/ 사이드카)를 생성한다. Obsidian은 같은 폴더를 위한 인간 인터페이스 편집기일 뿐이며, .obsidian/ 디렉터리는 Seahorse가 무시하고 절대 요구하지 않는다.

레거시 Obsidian 볼트를 마이그레이션

기존 Obsidian 노트(frontmatter 없거나 레거시 tags/created frontmatter)는 아직 표준 형식이 아니다 — seahorse index rebuild는 그런 노트에서 정직하게 실패한다. seahorse frontmatter migrate가 변환한다:

# Preview: classify every note, write nothing (always exit 0):
seahorse frontmatter migrate --vault myvault --dry-run
# Apply: convert legacy notes, leave canonical notes untouched, refuse
# incompatible notes:
seahorse frontmatter migrate --vault myvault
# Rebuild the sidecar index from the converted notes:
seahorse index rebuild --vault myvault

Apply는 비호환 노트가 전체 마이그레이션을 막으면 exit code 97로 종료한다 — 매니페스트 요약을 먼저 인쇄하여 운영자가 어떤 노트에 수동 처리 필요한지 알 수 있도록 한다. --resume은 마지막 매니페스트 이후 변경되지 않은 노트를 건너뛴다. --batch-size는 매니페스트 체크포인트 주기를 설정한다. 마이그레이션은 seahorse init 이전에도 동작한다(.md 파일 + 매니페스트만 건드린다).

첫 실행: 시맨틱 임베딩 모델(mE5-small, ~235MB)은 첫 remember/recall에서 지연적으로 다운로드된다. — CLI가 그 사실을 알리므로 첫 호출이 멈춘 것처럼 보이지 않는다. seahorse status는 현재 겁색 방식(hybrid RRF (model cached) vs current-state listing — 설치 seahorse-memory[embeddings] for semantic recall)을 표시한다.

다른 메모리 도구와의 비교

순위가 아니라 검증된 사실의 비교이다. 출처: 프로젝트의 최신 분석(연구 노트 및 아래 인용되는 주장).

범례: ✓ 예 · ✓픽· ~ partial · ✗ 아니요 · — 검증되지 않음.

가장 중요한 두 사실: mem0는 벤치마크 수치를 만들어내는 기능을 페이월 뒤에 가두어 두었고 Zep는 자가 호스트를 포지션하고 클라우드 전용로 전환했다. Seahorse는 기본적으로 로컬 우선이며, 벤치마크 하네스를 저장소에 게시하고, 메모리 형식을 이식 가능하게 유지하여 절대 잠금되지 않도록 한다.

벤치마크

Seahorse는 재현 가능한 벤치마크 하네스(LMEB-S, LongMemEval 벤치마크의 하위 표본)를 포함하며, 단서와 함께 자체 수치를 공개한다. 포인트는 리더보드가 아니라 정직하고 재현 가능한 측정이다.

Caveat: 이번 실행은 subsample(n≈470–500 질문, 전체 데이터셋이 아님)을 사용하고, 관련 판정은 작은 LLM이 사람 검증 없이 수행했으며, 검색만 측정하고 에이전트의 최종 응답을 측정하지 않는다. Cross-encoder 리랭킹을 시도했지만 채택하지 않았다 — recall@10을 0.11로 낮췄고, 대기가 1.2초였다. 전체 방법론과 재현 명령은 docs/benchmark.md.

이 수치는 하위 표본에서 작은 심판자로 검색 순위만 측정하는 것으로, 다른 메모리 시스템이 발표하는 엔드 투 엔드(전체 정확도) 점수(예: Graphiti 63.8%, Mem0 94.8, Hindsight 91.4%)와 비교할 수 없다. 비교하지 않는 방법은 docs/benchmark.md를 참고.

FAQ

에피소드란 무엇인가요? 하나의 메모리 레코드입니다: 두 개의 시간 축(valid_at — 사실이 참이 된 시점, created_at — 기록된 시점), 출처(provenance) 및 인지 type을 담은 YAML frontmatter이 포함된 markdown 파일입니다. 포맷은 버전 관리되고 docs/f3.1-format.md 문서화되었습니다.

왜 Obsidian인가요? 인간이 메모리 시스템의 일부이기 때문입니다. 에이전트는 당신이 편집하는 같은 볼트에 기록합니다 — markdown은 읽을 수symple클라우드는 git diff 할 수 있고 감사 가능합니다. 에이전트가 틀리면 데이터베이스가 아니라 노트를 바로잡습니다.

claude-mem과 다른 점은? claude-mem은 그들만의 스키마에 세션 관찰을 저장합니다. Seahorse는 개방형, 이중 시간 표준이며 이식 가능한 포맷과 인간이 읽을 수 있는 구역을 가지며 — seahorse import가 claude-mem 관찰을 표준 에피소드로 마이그레이션하므로, 경쟁자가 아니라 다리 역할을 합니다.

LLM이 필요한가요? 아니요. 결정적 스킵 경로는 대부분의 쓰기 작업에서 기본값입니다(비용이 거의 없음). LLM 추출은 선택 사항이며(seahorse-memory[llm]), 비용을 정당화할 수 있는 소수의 에피소드에만 사용됩니다.

무료인가요? 네. Apache-2.0, 로컬 우선(local-first), 제로 인프라(zero-infra)입니다. 관리형 SaaS와 엔터프라이즈 등급은 향후 계획되어 있습니다(프로젝트의 전략 노트 참조).

기여하려면 어떻게 하나요? CONTRIBUTING.md에서 개발 환경 구성, 테스트/린트 명령, 풀 리퀘스트 워크플로를 확인하세요.

로드맵

ROADMAP.md에서 무엇이 구축되어 있고, 무엇이 다음 단계인지, 프로젝트의 방향을 확인하세요. 릴리스 기록은 CHANGELOG.md에 있습니다.

에이전트 표면 — 메모리 네이티브 프리미티브 7개 + 절차적/읽기 전용 도구 7개

stdio MCP(io.seahorse.memory/v1, 프로토콜 고정 2025-11-25)로 노출되며 CLI에서도 동일하게 제공됩니다. 이들은 일반적인 CRUD가 아니라 메모리 프리미티브입니다. 에이전트는 사람이 기억을 말하듯이 remember / recall / improve / forget을 호출하고 이해합니다.

7가지 프리미티브(쓰기 + 회수):

추가로 7가지 절차적/읽기 전용 도구가 있습니다:

세 가지는 점진적 공개를 제공합니다: 먼저 저렴한 목록(INDEX), 그다음 TIMELINE 체인, 그리고 필요한 경우 전체 레코드(FULL). 이로써 공통 경로를 저렴하게 유지합니다.

제공되는 기능

• stdlib sqlite3 + sqlite-vec(FTS5 * vec0) 기반의 이중 시간(bi-temporal), 추가 전용(append-only) 에피소드 저장소, 스키마 자동 마이그레이션.

• CLI와 stdio MCP 모두에서 7개의 메모리 프리미티브와 7개의 절차적/읽기 전용 도구 제공(총 14개 도구).

• 점진적 공개(INDEX / TIMELINE / FULL) 및 특정 시점 프로젝션.

• 하이브리드 시맨틱 검색: recall은 관련성에 따라 순위를 매깁니다 — sqlite-vec kNN + FTS5 BM25를 Reciprocal Rank Fusion으로 융합하고, 실제 엠바이더가 연결되면 특정 시점 라우팅(state_at / known_at)을 사용합니다. 쓰기 경로와 seahorse index rebuild는 vec0/FTS를 채웁니다(최선 effort — 임베더 실패해도 에피소드 쓰기는 실패하지 않습니다).

• 정직한 저하: embeddings extra가 없거나(또는 벡터가 채워지지 않은 경우) recall은 현재 상태 목록(score 0.0, 순위 없음)으로 대체하고, 특정 시점 recall은거부됩니다 — 순위없이도 엔진은 계속 작동합니다.

• 옵트인 감쇠 랭킹(기본 꺼짐): FAMA 스타일의 에빙하우스 망각 곡선이 오래된 지식을 연령에 따라 가중치를 낮춥니다(score' = score · 2^(-age/half_life)), 유형별 반감기 사전 확률이 제공됩니다. 기본적으로 꺼져 있어 순수 RRF 지문이 비트 동일하게 유지됩니다.

• LLM 추출: 실제 멀티-LLM 경로(ollama / gemini / groq / openrouter / openai / anthropic / deepseek / vllm, 로컬 우선)와 엄격한 스키마 검증기 + 복구 루프, 재시도/폴백 체인, 운영용 비용 상한을 제공합니다(로컬 및 무료 티어 모델은 $0). seahorse init --llm으로 초기화합니다. 대부분의 쓰기 작업에서는 스킵 경로가 여전히 거의 0비용 기본값입니다.

• 로컬 우선 CI 게이트: 실제 추출 경로는 CI에서 패밀리의 가장 약한 모델(ollama/qwen3:0.6b)로 실행됩니다. 검증기 + 복구가 부담을 담당하므로, 이 경로는 네이티브 구조 출력이나 강력한 모델에 조용히 의존하지 않습니다.

• 대체(improve)와 소프트 딜리트(forget) 전체 기록을 보존합니다.

• 배치 증류(seahorse consolidate): 다수 에피소드를 단일 통합 노트로 증류합니다 — 기본은 결정적으로, 옵션인 LLM 합성(--synthesis llm)과 대체(--supersede)를 지원하여 통합 노트가 원본 소스를 대체할 수 있습니다 - 즉 통합 노트가 자신의 소스를 대체합니다.

• 프론트매터 가져오지/내보내기(README가 사람이 읽을 수 있고 휴대 가능한 온디스크 계약).

• 레거시 볼트 이주: seahorse frontmatter migrate는 레거시 Obsidian 노트를 변환합니다. --dry-run 미리보기, --resume, 및 호환되지 않는 노트가 전체 마이그레이션을 막으면 정직하게 exit 97을 제공합니다.

• 정직한 종료 코드와 stderr에 구조화된 {"error": {...}} 봉투. 에이전트와 스크립트는 seahorse_code / cli_code를 결정적으로 분기할 수 있습니다.

일부 CLI 명령은 연결되어 있지만 의도적으로 이유와 함께 exit 75를 반환합니다(expire, revalidate, index verify). 그러므로 표면은 아직 구현되지 않은 것을 조용히 무시하는 대신 정직하게 알려줍니다. llm_partial은 완전히 예약되어 있습니다.

스택

• Python ≥ 3.11. 저장소는 stdlib sqlite3 + sqlite-vec을 사용합니다(제로 인프라 단일 파일; vec0 가상 테이블 + FTS5).

• numpy는 임베딩 블롭 형태에 사용됩니다.

• Pydantic v2는 표준 Episode 계약(핵심 유형 시스템)에 사용됩니다.

• Typer는 CLI 표면(사용자와 스크립트)을 위해 사용됩니다. seahorse.cli로 제한됩니다.

• stdio JSON-RPC 2.0은 MCP 에이전트 표면에 사용됩니다(직접 작성한 프레이밍, stdlib 전용 seahorse.mcp 패키지 — import seahorse.mcp는 Typer를 로드하지 않습니다).

• ruamel.yaml + python-frontmatter은 프론트매터 어댑터에만 사용됩니다.

• FastEmbed ONNX + onnxruntime (기본 설치 미포함): mE5-small 번들의 기본값은 model_O4.onnx(fp32, ~235MB) — Apple Silicon에서는 int8/fp16 아티팩트를 휴대할 수 없고, 공개 표준은 Windows/Linux/macOS에서 실행되어야 합니다. 휴프 가능 int8 번들은 이후에 측정해서 진행할 것입니다.

• LiteLLM (기본 설치 미포함): LLM 추출 경로의 100개 이상의 provider 표면을 통합합니다. escape 없이도 seahorse.llm은 여전히 import됩니다(계약 + StubLLMClient), 실제 경로는 설정 힌트와 함께 llm→skip으로 저하합니다.

FastAPI / SQLAlchemy / Postgres 스택은 이후 멀티 에이전트 등급(Postgres + pgvector)으로 계획되어 있습니다. README는 대상 아키텍처가 아니라 현재 제공되는 것을 명시합니다.

테스트

• 단위 + 통합: uv run pytest (커버리지 ≥ 80% 게이트).

• 신규 사용자 e2e: scripts/e2e-fresh-user.sh — 클린하고 분리된 HOME에서 install → init → core CLI → embeddings → LLM → [import] → MCP 전체 흐름입니다(실제 ~/.claude / ~/.claude-mem을 건드리지 않습니다).

• 환경 매트릭스: scripts/e2e-matrix.sh — 설치 방법 × extras × Obsidian × Ollama × 온라인/오프라인 × 볼트 상태 × 동시 상태 조합에 대해 신규 사용자 흐름을 실행합니다. --ci-subset은 CI-safe 조합(core_min + uv_sync_dev)을 실행하고, --list는 모든 목록 조합을 보여줍니다.

• 코어 스트레스: scripts/stress-core.sh — 1000+ 에피소드 수집, 재집중(recall) --top-k 100 p95 \≤ 250ms(프로세스 내부 롤슬러), 동시 단일 작성자, reindex, 멱등 import(improve / forgetchain).

기여

기여을 환영합니다. CONTRIBUTING.md에서 개발 환경 구성, 테스트/린트 명령, 풀 리퀘스트 워크플로를 확인하세요. 릴리스 기록은 CHANGELOG.md에 있습니다.

라이선스

Apache-2.0. LICENSE 참조.

현재 상태

v0.10.0. 메모리 엔진은 클린 설치에서 엔드투엔드로 작동합니다: 에피소드 쓰기, 하이브리드 의미 검색으로 회수, 실제 멀티-LLM 경로(로컬 우선, CI 게이트)로 추출, improve 및 forget, 그리고 stdio MCP로 에이전트 서비스. 벡터가 채워져 있고 엠베디더가 연결되어 있을 때 recall 명령은 관련성으로 순위를 매기고, 그 외에는 현재 상태 목록으로 정직하게 저하합니다. 옵션인 감쇠 랭킹 바이어스(기본 꺼짐)는 오래된 지식을 연령별로 가중치를 낮춥니다. seahorse import는 클라우드-mem 관측값을 에피소드로 가고, 배치 증류(seahorse consolidate)는 여러 에피소드를 하나의 통합 노트로 바꾸며 opt-in LLM 합성과 supersession을 지원합니다. 벤치마크 하네스는 저장소에 포함되며, docs/benchmark.md에 주의사항과 재현 명령이 있습니다. 다음 단계는 What works와 ROADMAP.md를 참조하세요.