hippocampus
# Hippocampus
Memoria personal en grafo con superficie **HTTP + MCP**, reemplazo de Obsidian/Engram.
Stack: uv · Python 3.11+ · SQLModel + SQLite (FTS5) · FastAPI + FastMCP · Typer · Rich.
## Arranque
```bash
uv sync # OBLIGATORIO
uv run hippocampus init <db-path> # bootstrap (crea BD + siembra)
uv run hippocampus serve # HTTP+MCP en 127.0.0.1:27130
```
Subcomandos: `init`, `serve`, `mcp` (stdio), `graph` (mapa interactivo en HTML, `--tui` para la vista de tablas), `backup` (dump SQL).
## Vista del grafo
_Captura del grafo completo (seleccion: Image 2)._
## Arquitectura
Clean Architecture por capas (dependencias → adentro):
- **`api/`** — HTTP/MCP transporte (cero lógica).
- **`schemas/`** — Contrato API (Pydantic, D26).
- **`core/`** — Dominio (búsqueda-y-enlazar, grafo, técnica).
- **`db/`, `models/`** — Persistencia (SQLModel, FTS5, seed).
Dos espacios aislados por **construcción** (sin columna `space`):
1. **Personal (grafo):** nodos → edges → documents + attachments. Reemplaza Obsidian.
2. **Técnico (Engram-style):** `observations` con status/type. Reemplaza Engram.
Ver `docs/sdd-hippocampus.md` (SDD completo) y `docs/todo-hippocampus.md` (checklist) para detalles.
## Docs
- `docs/architecture.md` — principios y estructura.
- `docs/data-model.md` — esquema ER (8 tablas + FTS).
- `docs/core-services.md` — servicios de dominio (búsqueda-y-enlazar).
- `docs/http-mcp-api.md` — transporte (15 tools).
- `docs/e2e-flows.md` — flujos reales verificados.
- `docs/startup-and-init.md` — arranque + NO_INIT.
- `docs/runtime-launchd.md` — autostart en sesión.
- `docs/workspace-rewiring.md` — integración con `psychologist`.
## Specs (privado)
- `docs/specs/sdd-hippocampus.md` — diseño detallado (decisiones D1–D26, requisitos R1–R13).
- `docs/specs/todo-hippocampus.md` — checklist de implementación (Fase 0 completa).
- `docs/specs/sdd-obsidian-migration.md` — migrador determinístico Obsidian→hippocampus.
TDQS
Scored across 21 tools
The three prefixed domains (personal/tech/conversation) are clearly separated, and most tools target a distinct resource or action. Within personal, however, personal_provenance and personal_get_node both expose raw document text, and personal_neighbors/personal_graph both return graph-like views, requiring careful reading of descriptions.
The personal_/tech_/conversation_ prefixes create clear namespaces, and most tools follow a verb_noun pattern. A few personal_ names are bare nouns (provenance, neighbors, graph) rather than action verbs, which is a minor but noticeable inconsistency.
21 tools is on the heavy side for a single MCP server, even though the load is distributed across three distinct modules. The count feels manageable but exceeds the typical well-scoped range.
Core workflows are well covered: creating and linking entities, adding documents/attachments, searching and retrieving content, updating tech observations, and importing/auditing conversations. The main gaps are the lack of a general delete/detach operation and limited batch listing, but these can usually be worked around.