Seahorse

Memoria persistente y bi-temporal para agentes de LLM: local-first, nativa de MCP y legible con Obsidian.

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

Por qué

Los agentes de LLM empiezan cada sesión desde cero. La ventana de contexto no es memoria: es un bloc de notas que se resetea, y es demasiado pequeña para contener todo lo que un agente ha aprendido a lo largo de semanas de trabajo. Las herramientas que intentan solucionar esto tienen sus propios problemas:

• Olvidan muy mal. La mayoría de los sistemas de memoria acumulan hechos para siempre y nunca resuelven las contradicciones: un agente «recuerda» que un usuario vive en Madrid y qué y un nobody al same time, sin forma de saber cuál es la actual.

• Son opacos. La memoria vive en una base de datos propietaria que la persona no puede leer, editar ni auditar. Si el agente se equivoca, no hay manera de corregirlo.

• Son caros de alimentar. Cada episodio atraviesa un LLM, de modo que escribir miles de hechos pequeños cuesta dinero real.

• Te encierran en el plazo. Adoptar un sistema de memoria a menudo implica adoptar también su runtime, su proveedor o su ecosistema.

• No puedes fiarte de sus benchmarks. Las propias cifras del campo son difíciles de reproducir: el benchmark LOCOMO tiene un 6.4% de respuestas doradas incorrectas, la reproducción de Mem0 está rota (issue #2800), y los scores de embeddings de MTEB no predicen el rendimiento de recuperación de memoria (LMEB, arXiv 2603.12572).

Seahorse es un enfoque diferente: un estándar de memoria abierto, portable y bi-temporal que un agente escribe y lee, que una persona puede leer y corregir, y que no te encierra en ningún runtime ni proveedor.

Related MCP server: agentcairn

Para quién es

• Desarrolladores que crean agentes (Claude Code, Cursor, Codex o los propios) que quieren que el agente recuerde decisiones y contexto a lo largo de las sesiones.

• Usuarios avanzados de Obsidian que quieren que sus notas sean más que un archivo estático: lo que una base de conocimiento que un agente pueda consultar y mantener.

• Equipos que quieren memoria portable — un formato que puedan migrar entre proveedores sin: repasar el historial.

Caso de uso: Claude Code con memoria persistente

La forma más rápida de ver Seahorse es darle a Claude Code una memoria que sobreviva entre sesiones. Tres pasos:

1. Captura sesiones. seahorse setup instala los hooks del observador en ~/.claude/settings.json; seahorse observe start ejecuta el proceso de captura. Cada sesión se registra firmada como episodios — skip-first (coste casi nulo), redactados, con un resumen determinista.

seahorse setup
seahorse observe start

2. Recuerda entre sesiones. El hook SessionStart inyecta seahorse context en la siguiente sesión, de modo que el agente arranca con lo que aprendió antes. Pregunta directamente con seahorse recall:

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

3. Aporta tu memoria existente. Si ya usas med dine, seahorse import migra sus observaciones a episodios canónicos — sin frame no, sin lock-in:

seahorse import --mode commit

La diferencia principal: el agente escribe en the same vault que editas en Obsidian. Cada episodio es un archivo markdown con YAML frontmatter — legible, abecedario por humanos, con diff en git y auditable. La memoria del agente no es una caja negra: son tus notas.

Úsalo desde el agente (MCP)

Seahorse está pensado para agentes: la superficie de memoria es un servidor MCP nativo por stdio (io.seahorse.memory/v1) al que se puede conectar cualquier agente que haga muestras que haga MCP. La CLI es para humanos y scripts; los agentes hablan con seahorse-mcp.

Registra el servidor en Claude Code (ámbito local, por defecto):

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

El -- es obligatorio: separa las propias opciones de Claude del comando del servidor. Usa --scope project para compartir el servidor con un equipo por .mcp.json (incluido en git). Verifica con claude mcp list (should show show ✔ Connected) y claude mcp get seahorse-mcp.

O configúralo en .mcp.json en la raíz del proyecto (funciona con cualquier cliente MCP):

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

Nota: ~ no se expande en .mcp.json — usa ${HOME} u un ruta absoluta. (Los mcpServers en settings.json son ignorados en silencio; los servidores MCP viven en ~/.claude.json para ámbito de ajeno.al local y en .mcp.json para ámbito de proyecto.)

Una vez conectado, el agente verá las 14 herramientas de memoria — 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 (ver [La superficie del agente](#la-superficie-del-age2e--but... targets? Actually the original anchor must stay unchanged. Let me keep original anchor.

The observer (seahorse setup) is a separate piece: it captures Claude Code sessions — into episodes. The MCP server is how the agent reads and writes memory. Both types exist in each other: capture sessions, then recall across them.

Cómo funciona

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

Un agente habla con seahorse-mcp a través de stdio MCP. El motor guarda cada episodio dos veces: una files in a single-file SQLite database (sqlite-vec for vector searches, F1, with full-text FTS5), optionally as a Markdown file with F3.1 frontmatter in the vault. Human edits the same markdown. The format is versioned and documented in docs/f3.1-format.md.

Inicio rápido

# 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

The seahorse console script is for humans and shell scripts; seahorse-mcp is for agents. The seahorse mcp subcommand invokes the same stdio server as «seahorse-mcp», so both agent entry POI sont fort equivalent. Para conectar un agente, ver Úsalo desde un agente.

Requisitos previos

• Python ≥ 3.11 (cualquier versión 3.11/3.11-123 recursiva works). The sqlite3 of the interpreter must support enable_load_extension (sqlite-vec needs it); the majority contact standard beastry applications — seahorse doctor the line as FAIL if not.

• Obsidian es voluntario. Seahorse corre on any directory of markdown — seahorse init creates un sidecar .seahorse/ en una simple directorio. Obsidian es el editor humano para ese directorio; the .obsidian/ verzeichnis is ignored by Seahorse, and never require.

Migrar un vault de Obsidian heredado

Un vault existing of Obsidian notes (without frontmatter or legacy tags/created frontmatter) is not yet in the canonical format — seahorse index rebuild falls bene in those notes. seahorse frontmatter migrate migrates them:

# 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 termine with exit code 97 when incompatible notes block full migration — manifest summary(s) printed first work so operator sees which notes require manual resolution. --resume skips notes that have changed since the last manifest; --batch-size sets the manifest checkpoint cadence. Migration works before seahorse init (only touches .marge files + the manifest).)

Primera ejecución: the semantic-era model (mE5-small, ~235MB) is downloaded dreamily in the first remember/recall; — the CLI communicates it so the first call looks not hung. seahorse status shows the active retrieval regime hybrid: (hybrid RRF (model cached)vscurrent-state listing — install seahorse-memory[embeddings] for semantic recall`).

Compared with other memory tools

Compared with verified facts, no ranking. Sources: the research state of the art from the project (see research notes and statements below).

Legend: ✓ yes · ~ : partial · ✗ no · — not verified.

Lo que más probablemente importa: two essential facts: mem0 places behind a paywall the features that produce its ads benchmark numbers and Zep abandona self-host para cloud-only. Seahorse is local-first by default, publishes its benchmark harness in the repo, and keeps the memory format porta tile — therefore you are never locked in.

Benchmark

Seahorse ships a reproducible benchmark harness (LMEB-S, a subsample of LongMemEval) and publishes its own numbers — with caveats. An object is not a leaderboard; the use is an state-nested. Admirable reproducible measurement.

Caveats: the run uses a sample (n≈470–500 questions, no full data); relevance is judged by a small LLM without human validation; it measures retrieval only, not the agent’s final answer. A cross encoder reorder ran and was rejected — arrival recall@10 to 0.11 mouse latency of 1.2s. Full methodology and reproduction commands in docs/benchmark.md.

Las cifras miden solo recuperaciones de ranking rankiza las keywords in a sample with e, no small judge — do not compare with end-to-end accuracy scores ((((p.ej., Graphiti 63.8%, Mem0 94.8, Hindsight 91,4%). See docs/benchmark.md — how not to compare.

FAQ

¿Qué es un episodio? A single memory record; a markdown file: with YAML the frontmatter with two axes of time (valid_at — when it happened true; y created_at — when it recorded), provenance and cognitive type. the format is versioned and documented in docs/f3.1-format.md.

Why Obsidian? Because the human is part of the memory system. An agent writes in the same vault you edit: — markdown is legible, diffable in git, and auditable. If the agent is wrong, you cannot correct the note, no a data base.

¿En qué se process current claude-mem? claude-mem golf session observations in their own schema. Seahorse is an open, bi-temporal standard with an immutable format and a layer, human-readable — sea seahorse import migra observe von claude-mem to canonical episodes; it is a bridge, no competidor.

Now I'm done. But I noticed something: in the section "Úsalo desde...", I wrote a link with La surface. In the original, there's an internal link to "#the-agent-surface--7-memory-native-primitives--7-proceduralread-only-tools". I must include that verbatim. I initially drafted with the anchor but then when writing "ver" I truncated. Need to correct.

Also by the final output I jumbled in places. Let me correct and produce final clean output. Ensure no corruption.

I'll now rewrite the full answer cleanly, corrected.

Also the table "Zep / Graphiti" should be "Zep / Graphiti" exactly. In my draft, I almost wrote "Diagramita". No.

Let's rewrite all carefully.

One important correction: In the "Comparison" section paragraph: "Los dos hechos que más importan: mem0 y el payware de las funciones que producen sus cifras benchmark and Zep abandonó self-host para cloud-only." Let's make proper: "Los dos hechos que más importan: mem0, payware: las features that produce their benchmark numbers remain hidden behind paywall and Zep abandoned self-host edition for cloud-only."

Wait better: "mem0 paywall the features that produce its benchmark numbers" -> "mem0 hay vacates de pago la functionality that generates its benchmark numbers" -> "mem0 esconde tras un pago las funcionales funcionalidades that producen sus cifras de benchmark". Yes.

Now "If something with "you never locked in" -> "para que nunca quedes encerrado".

Now check "the second fact": "Zep abandoned self-host for cloud-only" -> "Zep abandoned the self-hosting to go cloud-only". Good.

Let me finalize with proofreading.

Also, in the introduction, the phrase "accessible" in original "Obsidian-presentable" — "legible con or Obsidian". Good.

Let me output final in one go, ensuring correct GXP placement.

But let me also cross-check the validity of the O124 quote: I see the "The observer (seahorse setup) . . ." In final output, I should open with "The observer..." — correct.

Let me fix the anchor link in text "ver The agent surface" — keep anchor original.

Also "An The agent surface"? In original: "(see The agent surface" — the parentheses are around. Keep.

Let me produce the entire final text now with no further hiccups.# Seahorse

Memoria persistente y bi-temporal para agentes LLM — local-first, nativa de MCP y legible con Obsidian.

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

Por qué

Los agentes LLM empiezan cada sesión desde cero. La ventana de contexto no es memoria: es un bloc de notas que se resetea, y es demasiado pequeño para contener lo que un agente ha aprendido en semanas de trabajo. Las herramientas que intentan arreglar esto tienen sus propios problemas:

• Olvidan muy mal. La mayoría de los sistemas de memoria acumulan hechos para siempre y nunca resuelven las contradicciones: un agente «recuerda» que un usuario vive en Madrid y al mismo tiempo en Barcelona, sin ninguna manera de saber cuál es el current.

• Son opacos. La memoria vive en un almacén privado que el humano no puede leer, editar ni auditar. Si el agente se equivoca, no hay manera de corregirlo.

• Son caros de alimentar. Cada episodio pasa por un LLM, de modo que escribir miles de hechos pequeños cuesta dinero de verdad.

• Te encierran en el plazo. Adoptar un sistema de memoria muchas veces implica adoptar también su runtime, su proveedor o su ecosistema.

• Sus benchmarks inspiran poca confianza. Los propios números del campo son difíciles de reproducir: el benchmark LOCOMO tiene un 6,4% de respuestas de oro incorrectas, la reproducción de Mem0 está rota (issue #2800), y las puntuaciones de embeddings MTEB no predicen el rendimiento en la recuperación de memoria (LMEB, arXiv 2603.12572).

Seahorse es un enfoque distinto: un estándar de memoria abierto, portable y bitemporal al que el agente escribe y del que lee, que un humano puede leer y corregir, y que no te ata a ni ningún runtime ni a ningún proveedor.

Para quién es

• Desarrolladores que construyen agentes (Claude Code, Cursor, Codex o tu propio agente) que quieren que el agente recuerde decisiones y contexto entre sesiones.

• Usuarios avanzados de Obsidian que quieren que sus notas no sean solo un archivo estático: instead a base de conocimiento que un agente pueda consultar y mantener.

• Equipos que quieren memoria portable — a format that they can transfer between proveedores sin tener que repetir historial.

Caso de uso: Claude Code con memoria persistente

La forma más rápida de experimentar Seahorse en la dar claude Code una memoria que sobrevive entre sesiones. Tres pasos. ...

Wait, I have to ensure doc starts with "## Caso de uso: Claude Code con memoria persistente". Good.

Let me rewrite the whole final cleanly. I'll stop the impromptu cleanup; drafting all.

Now# Seahorse

Memoria persistente y bi-temporal para agentes LLM — local-first, nativa de MCP y legible con Obsidian.

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

Por qué

Los agentes LLM empiezan cada sesión desde cero. La ventana de contexto no es memoria: es un bloc de notas que se restablece, y es demasiado pequeña para contener lo que un agente ha aprendido a lo largo de semanas de trabajo. Las herramientas que intentan resolverlo tienen sus propios problemas:

• Olvidan muy mal. La mayoría de los sistemas de memoria acumulan hechos para siempre y nunca resuelven las contradicciones: un agente «recuerda» que un usuario vive en Madrid y en Barcelona a la vez, sin manera de saber cuál es la actual.

• Son opacos. La memoria vive en un repositorio propietario que el humano no puede leer, editar ni auditar. Si el agente se equivoca, no hay forma de corregirlo.

• Son caros de alimentar. Cada episodio pasa por un LLM, de modo que escribir miles de datos pequeños cuesta dinero de verdad.

• Te atrapan. Adoptar un sistema de memoria a menudo implica adoptar también su runtime, su proveedor o su ecosistema.

• Sus puntosajes comparativos no son fiables. Los números del propio campo son difíciles de reproducir: el benchmark LOCOMO tiene un 6,4% de respuestas de oro incorrectas, la reproducción de Mem0 está rota (issue #2800), y las posiciones incrustadas de MTEB no predican el rendimiento de recuperación de memoria (LMEB, arXiv 2603.12572).

With Seahorse es un approach list: un estándar de memoria abierto, portable y bi-temporal al que un agente le escribe y del que lee, que una persona puede leer y corregir, y que no te encierra en ningún tipo de ejecución ni proveedor.

Para quién es

• Desarrolladores que crean agentes (Claude Code, Cursor, Codex o el mismo — propios) que quieren que el agente recuerde decisiones y contexto entre sesiones.

• Usuarios avanzados de Obsidian que quieren que sus notas sean algo más que un archivo estático: a una base de conocimiento consultable y a negocio.

• Equipo que quiere memoria portable — un formato que pueda replicarse entre proveedores sin rehecho del historial.

Case de use: Claude Code con memoria persistente

La vía más rápida para ver Seahorse es give a Claude Code una memoria que sobreviva entre sesiones. Tres pasos:

1. Captura sesiones. seahorse setup instala los hooks del observador en ~/.claude/settings.json; seahorse observe start ejecutes el proceso de captura. Cada sesión se registra así como episodios — primer-omiten (coste casi cero), redacted, con un resumen determinista.

seahorse setup
seahorse observe start

2. Recordar entre sesiones. El hook en SessionStart inyecta seahorse context en la siguiente sesión, de modo que el agente arranca con lo aprendido antes. Puedes preguntar directamente through seahorse recall:

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

3. Trae tu memoria ya existente. Si ya usas claude-mem, seahorse import migra sus observaciones a episodios canónicos — sin repetir, sin dependencia:

seahorse import --mode commit

La clave característica: el agente escribe en el mismo vault que tu editas en Obsidian. Cada episodio es un archivo markdown con frontmatter YAML — legible, edita, diff en git, y auditable por un humano. The memory of the agent is not a black box; it's your notes.

Úsalo desde un agente (MCP)

Seahorse está pensado para agentes: the memory resource is a stdio MCP server (io.seahorse.memory/v1) to which any agent that speaks MCP can connect. La CLI esto?

Registra el servidor en Claude Code (ámbito local, por defecto):

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

El -- es obligatorio: distingue las propias banderas de Claude de la orden del servidor. Use --scope project to share the server with a team through .mcp.json (in git). It is verifies with claude mcp list (should show ✔ Connected) and claude mcp get seahorse-mcp.

**

¿Necesito un LLM? No. La ruta de omisión determinista es la predeterminada para la mayoría de las escrituras (coste casi nulo). La extracción con LLM es opcional (seahorse-memory[llm]) y está reservada para los pocos episodios que la justifican.

¿Es gratuito? Sí. Apache-2.0, local-first, sin infraestructura. Un SaaS gestionado y un nivel empresarial están previstos para el futuro (véanse las notas de estrategia del proyecto).

¿Cómo contribuyo? Consulta CONTRIBUTING.md para la configuración de desarrollo, los comandos de test/lint y el flujo de trabajo de solicitudes de extracción.

Hoja de ruta

Consulta ROADMAP.md para ver qué está construido, qué es lo siguiente y la dirección del proyecto. El historial de versiones está en CHANGELOG.md.

La superficie de agente — 7 primitivas nativas de memoria + 7 herramientas procedimentales/de solo lectura

Expuesta a través de stdio MCP (io.seahorse.memory/v1, protocolo fijado en 2025-11-25) y reflejada en la CLI. Son primitivas de memoria, no CRUD genérico: un agente invoca remember / recall / improve / forget como un humano hablaría de la memoria.

Las 7 primitivas (escritura + recuperación):

Además hay 7 herramientas procedimentales/de solo lectura (skills + introspección de la fachada):

Tres niveles de recuperación ofrecen revelación progresiva: una lista barata primero (INDEX), la cadena bajo demanda (TIMELINE) y el registro completo solo cuando se necesita (FULL). Esto mantiene barato el camino habitual.

Qué funciona

• Almacén de episodios bi-temporal y de solo adición en sqlite3 del stdlib + sqlite-vec (FTS5 * vec0). Esquema con migración automática.

• Las 7 primitivas de memoria + las 7 herramientas procedimentales/de solo lectura, tanto en la CLI como en stdio MCP (14 herramientas en total).

• Revelación progresiva (INDEX / TIMELINE / FULL) y proyección de punto en el tiempo.

• Recuperación semántica híbrida: recall clasifica por relevancia — kNN de sqlite-vec + BM25 de FTS5 fusionados mediante Reciprocal Rank Fusion — con ruta que salva el tiempo (state_at / known_at) cuando hay un encode real conectado. La ruta de escritura y seahorse index rebuild pueblan el índice vec0/FTS (best-effort: un fallo del encoder nunca falla la escritura del episodio).

• Degradación honesta: sin el extra embeddings (o sin vectors poblados), recall se reduce al listado del estado actual (puntuación 0.0, sin ranking) y se rechaza la recuperación puntual — el motor sigue funcionando sin ordenar.

• Ranking de caída opcional (desactivado por defecto): una curva de olvido de Ebbinghaus estilo FAMA subresta la importancia del conocimiento obsoleto según la edad (score' = score * 2^(-age/half_life)), con prioridades de media per-tipo. Desactivado por defecto: la huella pura de RRF sigue siendo comparable entre sí.

• Extracción con LLM: una auténtica ruta multi-LLM (ollama / gemini / groq / openrouter / openai / anthropic / deepseek / vllm, local-first) con un validador de esquema estricto + bucle de reparación, cadena de reintentos/fallback y un límite de coste operativo (los modelos locales y de nivel gratuito cuestan $0). seahorse init --llm hace el arranque; la vía de omisión sigue siendo la opción por defecto de coste casi nulo para la inmensa mayoría de las escrituras.

• Gate de CI local-first: la ruta real de extracción se ejecuta en CI contra el modelo más débil de la familia.({ollama/qwen3:0.6b) para que el validador + reparación aguanten la carga — la ruta no depende silenciosamente de salidas estructuradas nativas ni de un modelo fuerte.

• Sustitución (improve) y borrado suave (forget) con historial completo preservado.

• Destilación por lotes (seahorse consolidate): destila muchos episodios en una sola nota consolidada — determinista por defecto, con síntesis LLM opcional (--synthesis llm) y supersesión (--supersede), de modo que la nota consolidada sustituye a sus fuentes.

• Importación/exportaciones de frontmatter para la capa de vault de Obsidian (markdown como contrato legible y portátilEn disco).

• Migración de legacy de vault: seahorse frontmatter migrate convierte las notas antiguas de Obsidian con una previsualización --dry-run, --resume, y con código de salida honesto 97 cuando hay notas incompatibles bloquean que se haga completa la migración.

• Códigos de salida honestos y un sobre estructurado {"error": {...}} para que los agentes y scripts puedan decidir de forma determinista con seahorse_code / cli_code.

Algunos comandos de la CLI est’ atados pero retornan deliberadamente el código 75 con su motivo (expire, revalidate, index verify), de modo que la superficie dice la verdad sobre lo que aún no está implementado, en lugar de no hacer nada en silencio. llm_partial sigue completamente reservado.

Stack

FastEmbed ONNX y onnxruntime:

• Python ≥ 3.11. sqlite3 de stdlib + sqlite-vec para el almacenamiento (un único archivo y sin infraestructura; tabla virtual vec0 + FTS5).

• numpy para la forma de los vectores.

• Pydantic v2 para el contrato canónico Episode (sistema de tipos central).

• Typer para la superficie CLI (humanos y scripts). Limitado a seahorse.cli.

• stdio JSON-RPC 2.0 para la superficie de agentes MCP (framing artesanal, paquete stdlib seahorse.mcp — import sea horse.mcp no carga Typer).

• ruamel.yaml + python-frontmatter , confinadamente al adaptador de frontmatter.

• FastEmbed ONNX + onnxruntime (extra embeddings, NO en la instalación por defecto): el paquete mE5-small trae model_O4.onnx por defecto (fp32, ~235MB) — no hay ningún artefacto int8/fp16 portable a Apple Silicon, y un estándar abierto debe correr en Windows/Linux/macOS. Puede completar una variante int8 portable y medida.

• LiteLLM (extra llm, NO en la instalación por defecto): unifica los más de 100 proveedores para la vía de extracción LLM. Sin el extra, seahorse.llm se puede importar correctamente (contrato + StubLLMClient) y la ruta real desciende de llm→skip con una pista de configuración.

La pila FastAPI / SQLAlchemy / Postgres está prevista para una capa multi-agente posterior (Postgres + pgvector). El README indica lo que se distribuye hoy, no el target architecture.

Pruebas

• Unitarias + integración: uv run pytest (umbral de cobertura ≥ 80%).

• E2E de nuevo usuario: scripts/e2e-fresh-user.sh: el flujo completo install → init → core CLI → embeddings → LLM → import → MCP desde un HOME limpio y aislado (nunca toca el ~/.claude / ~/.claude-mem real).

• Matriz de entornos: scripts/e2e-matrix.sh — el flujo de usuario nuevo atraviesa distintos entornos (método × extras × Obsidian × Ollama × online/offline × estado del vault × concurrencia). --ci-subset ejecuta los combos seguros para CI (core_min + uv_sync_dev); --list muestra todos.

• Stress del núcleo: scripts/stress-core.sh: ingiere 1000+ episodios, recall --top-k 100 p95 ≤ 250 ms (presupuesto de INDEX en proceso), un solo proceso de escritura concurrente, reindex, import idempotenta y cadena improve/forget.

Contribución

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para la configuración de desarrollo, las órdenes de test/lint y el flujo de trabajo de solicitudes de cambios. Historial de versiones en CHANGELOG.md.

Licencia

Apache-2.0. Ver LICENSE.

Estado actual

v0.10.0. El motor de memoria funciona de principio a fin desde una instalación limpia: escribe episodios, los recoge con recuperación semántica híbrida, los extrae con un camino real multi-LLM (local-first, CI), los mejora y los olvida, y sirve a un agente por stdio. El recall clasifica por relevancia cuando los vectores están presentes y el embedder está conectado; fuera de ese caso, degrada con honestidad a un listado del estado actual. El ranking por decaimiento optativo (para a explicar) en menos: prioriza lo más reciente por edad. es el motor continúa sin fallar. seahorse import migra observaciones de claude-mem a hazañas, y el destilado por lotes (consolidate) convierte muchas hazañas en una nota consolidada — puede sumar síntesis LLM y supersedence. El banco de benchmarks se incluye con avisos y los comandos de reproducción en docs/benchmark.md. Consulta Qué funciona y ROADMAP.md para saber más.