diff --git a/README.es-ES.md b/README.es-ES.md
index 6da2d86..bc1db5d 100644
--- a/README.es-ES.md
+++ b/README.es-ES.md
@@ -1,92 +1,211 @@
+<div align="center">
 
+<a href="#puesta-en-marcha-rápida">
+  <img src="assets/og.webp" alt="Session Recall — tus agentes de código olvidan; Session Recall, no. Una sola memoria para Claude Code, Codex y Cursor." width="100%" />
+</a>
 
-# session-recall
+<br />
+<br />
 
-*Traducción de la comunidad (gracias, @webbrain-one). Puede ir por detrás del
-[README en inglés](README.md), que es la referencia; versión en ruso:
-[docs/README.ru.md](docs/README.ru.md).*
+<strong>Memoria semántica compartida para Claude Code, Codex y Cursor.</strong><br />
+Encuentra una decisión antigua por su significado. Abre la evidencia en bruto. Continúa el trabajo.
 
-**Memoria compartida para Claude Code, Codex y Cursor.** Retoma el trabajo de hace un mes sin tener que reexplicarlo: Claude puede leer lo que Codex o Cursor resolvieron ayer, porque los tres alimentan un mismo índice. No es un archivo de resumen que alguien mantiene a mano: son los turnos reales, incluidas las llamadas a herramientas y el razonamiento, buscables por significado.
+<br />
+<br />
 
-```console
-$ session-recall index
-indexed 2175 chunks from changed transcripts
+[![Licencia MIT](https://img.shields.io/badge/license-MIT-b8f84f?style=flat-square&labelColor=11120f)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-b8f84f?style=flat-square&labelColor=11120f)](pyproject.toml)
+[![MCP nativo](https://img.shields.io/badge/MCP-native-b8f84f?style=flat-square&labelColor=11120f)](src/session_recall/server.py)
+[![Tests](https://img.shields.io/github/actions/workflow/status/AbsoluteMode/session-recall/test.yml?branch=main&style=flat-square&label=tests&labelColor=11120f)](https://github.com/AbsoluteMode/session-recall/actions/workflows/test.yml)
 
-your history: 1053 sessions spanning 168 days, 40,037 searchable fragments
-  Claude Code 372 · Codex 680 · Cursor 1
-  busiest: sidekey, trend_detection, glitch
-```
+<br />
 
-Entonces, tu agente dejará de preguntarte qué estabas haciendo:
+[English](README.md) · [Русский](docs/README.ru.md) · Español · [中文](README.zh-CN.md)
 
-> **tú:** estábamos arreglando el conflicto del token de autenticación entre los dos servicios, ¿en qué quedamos?
->
-> **agente:** *(recall_search → expand_around)* Ambos servicios compartían una cuenta OAuth, y el proveedor rota los tokens de refresco por cuenta, por lo que cada refresco invalidaba la copia del otro. Rechazaste el parche de directorio de credenciales compartidas por estar demasiado acoplado, y te decidiste por un servicio gestor propietario de la sesión. Las especificaciones nunca se escribieron: ese era el siguiente paso.
+*La versión en inglés es la de referencia; las traducciones pueden quedar rezagadas.*
 
-Cinco herramientas a través de MCP:
+</div>
 
-- `recall_search(query)` — encuentra una discusión pasada **por significado** (no por subcadena). Responde `{"anchors": [...], "degraded": null | str}`; `degraded` se establece cuando el proveedor de incrustaciones es inalcanzable y solo se ejecutó la coincidencia literal, para que el agente pueda indicarlo en lugar de confundir un fallo léxico con un historial vacío.
-- `expand_around(session_id, uuid)` — un cursor en el turno raw (llamadas a herramientas, salidas, pensamiento).
-- `step(session_id, uuid, direction)` — muévete a un turno adyacente (paso de cursor económico).
-- `grep(pattern)` — exploración bajo demanda de subcadenas en **todos** los transcripciones indexadas, incluidos los turnos internos (salida de herramientas, pensamiento) que nunca se convirtieron en fragmentos de búsqueda.
-- `recent_sessions()` — las sesiones pasadas más recientes primero (qué está activo, qué tan fresco es el índice).
+---
 
-Bajo demanda (sin autoinyección proactiva en v1). Local y de código abierto.
+Tus agentes de código recuerdan el chat actual. Tu trabajo vive repartido en meses de chats:
+sesiones retomadas, suscripciones en paralelo, worktrees, agentes distintos.
 
-`recall_search`, `grep` y `recent_sessions` también aceptan un opcional `scope_cwd`: pasa tu directorio de trabajo actual para limitar los resultados al repo actual (los worktrees colapsan a la raíz del repo); omítelo para recordatorios entre proyectos. Los resultados clasificados incluyen una marca de tiempo legible por humanos `when_human` junto con la época raw. Cada herramienta MCP acepta un `source` opcional (`claude`, `codex` o `cursor`); omítelo para usar el historial unificado. Los resultados incluyen la procedencia correspondiente. Las tres herramientas de descubrimiento también aceptan `on_date` para un solo día o `start_date` / `end_date` inclusivos (`YYYY-MM-DD`) más un `timezone` IANA opcional, para que un agente pueda restringir la recuperación a un día calendario local real en lugar de esperar que una fecha escrita en la consulta semántica afecte la clasificación. Si se omite `timezone`, Session Recall usa la zona horaria de la computadora que ejecuta el servidor MCP.
+Session Recall convierte ese historial en un único índice local-first y lo sirve de vuelta a
+través de cinco herramientas MCP bien acotadas. Una sesión recién abierta puede recuperar lo
+que Codex resolvió ayer y lo que Claude Code rechazó hace tres meses — con enlaces a los
+turnos reales, la salida de las herramientas y el razonamiento. No es un archivo de resumen
+que alguien mantiene a mano: la conversación original sigue siendo la fuente de verdad.
 
-**Estado:** v1, construido y validado con historial real. La clave del razonamiento de diseño está en [docs/decisions/](docs/decisions/).
+> **tú:** estábamos arreglando el conflicto del token de autenticación entre los dos
+> servicios — ¿en qué quedamos?
+>
+> **agente:** *(recall_search → expand_around)* Los dos servicios compartían una misma cuenta
+> OAuth, y el proveedor rota los tokens de refresco por cuenta, así que cada refresco
+> invalidaba la copia del otro. Rechazaste el parche del directorio de credenciales
+> compartidas por demasiado acoplado, y optaste por un servicio keeper como dueño de la
+> sesión. La especificación nunca llegó a escribirse — ese era el siguiente paso.
+
+## Qué obtienes
+
+| | Capacidad | Qué cambia |
+|---|---|---|
+| **Una sola memoria** | Claude Code, Codex y Cursor alimentan el mismo índice | Cambia de agente sin reiniciar la historia del proyecto |
+| **Recuperación semántica** | Busca por significado, no solo por palabras exactas | Recupera decisiones que puedes describir pero no citar |
+| **Navegación profunda** | Abre los turnos en bruto: llamadas a herramientas, salidas, razonamiento | Verifica la respuesta en lugar de fiarte de un resumen |
+| **Degradación honesta** | Una caída de la parte semántica se comunica explícitamente | Un respaldo solo literal nunca se hace pasar por búsqueda semántica |
+| **Local por defecto** | Incrustaciones ONNX incluidas y SQLite local | Empieza sin clave, sin servidor y sin cuenta |
+| **Recall acotado** | Filtra por repo, origen o fechas del calendario local | Deja los proyectos ajenos fuera de la respuesta |
+| **Respuestas de equipo** | Pregunta a la memoria local de un colega, con aprobación del dueño | Comparte contexto duramente ganado sin exponer sesiones en bruto |
+
+## Dónde compensa
+
+- **Arranque de sesión.** Una sesión nueva empieza ya en contexto — tanto si haces malabares
+  con varias suscripciones, como si saltas entre agentes o vuelves a una tarea que
+  «comentaste en algún momento».
+- **Bugs y regresiones.** Antes de arreglar nada, el agente pregunta al historial: *¿se había
+  visto ya este bug? ¿cómo se arregló? ¿por qué creímos que estaba arreglado?* Una recaída
+  deja de parecer un bug nuevo — y la corrección pasa de ser un parche a ser una excavación
+  en el componente.
+- **Procedimientos.** Explica un flujo de trabajo una sola vez — cómo leer una traza, cómo
+  desglosar el gasto de tokens por tarea — y cualquier sesión posterior lo repite sin que
+  haya que guiarla de nuevo.
+- **Causa y efecto.** Di «cambiemos esta decisión» y el agente busca el momento en que se
+  tomó: *«elegimos X por compatibilidad con Y — antes de cambiar nada, asegúrate de que Y
+  sobrevive»*.
+
+## Cinco herramientas, un solo flujo de trabajo
+
+La interfaz se mantiene deliberadamente pequeña:
+
+| Herramienta MCP | Úsala cuando |
+|---|---|
+| `recall_search(query)` | Recuerdas la idea, no las palabras exactas |
+| `expand_around(session_id, uuid)` | Encontraste un ancla y necesitas la evidencia que la rodea |
+| `step(session_id, uuid, direction)` | Necesitas el turno en bruto adyacente sin otra búsqueda |
+| `grep(pattern)` | Conoces un error, un símbolo, una ruta o un identificador exactos |
+| `recent_sessions()` | Quieres el trabajo más fresco — y la frescura del índice |
+
+```mermaid
+flowchart LR
+    Q["describe the old problem"] --> S["recall_search"]
+    S --> A["ranked anchor"]
+    A --> E["expand_around"]
+    E --> T["step next / prev"]
+    Q -. exact identifier .-> G["grep"]
+    R["what is current?"] --> RS["recent_sessions"]
+```
 
-## Cómo funciona
+Cada herramienta de descubrimiento acepta un `source` opcional (`claude` | `codex` | `cursor`),
+un `scope_cwd` para acotar los resultados al repo actual (los worktrees colapsan a la raíz
+del repo) y fechas del calendario local (`on_date`, o `start_date` / `end_date`, más un
+`timezone` IANA). Las anclas clasificadas llevan su procedencia y una marca de tiempo
+legible. `grep` escanea bajo demanda **todas** las transcripciones indexadas — incluidos los
+turnos internos (salida de herramientas, razonamiento) que nunca se convirtieron en
+fragmentos de búsqueda. Solo bajo demanda: sin inyección proactiva de contexto en cada prompt.
 
-Las transcripciones de Claude Code, las sesiones de Codex desde `~/.codex/sessions` y `~/.codex/archived_sessions`, y las conversaciones de Cursor comparten el mismo índice. Cursor se lee desde su SQLite local y cada conversación se conserva como una instantánea JSONL normalizada dentro del directorio de datos de session-recall; por eso `expand_around`, `step` y `grep` siguen funcionando aunque Cursor esté cerrado o se desinstale.
-Solo se incrusta la "superficie" de la conversación: los prompts del usuario y las respuestas de texto del asistente.
-Las llamadas a herramientas, resultados, razonamiento y otros datos de traza no se incrustan, pero permanecen accesibles bajo demanda mediante `expand_around` (y `step`) o `grep`. Las transcripciones originales de Claude/Codex y las instantáneas raw normalizadas de Cursor permanecen locales; solo la superficie de conversación extraída se envía al proveedor de incrustaciones configurado.
+<details>
+<summary><strong>Ver una llamada completa</strong></summary>
+
+```json
+{
+  "query": "why did refresh tokens conflict?",
+  "scope_cwd": "/work/keeper",
+  "source": "codex",
+  "start_date": "2026-05-01",
+  "end_date": "2026-06-30",
+  "timezone": "Europe/Moscow"
+}
+```
 
-La ruta sin configuración usa un modelo ONNX local elegido por idioma → SQLite (`sqlite-vec` KNN + FTS5, clasificación bm25) → top-k. Con una clave de Voyage se usa la ruta alojada de mayor calidad: `voyage-4-large` (dim 1024) → SQLite → `rerank-2.5`. La indexación es incremental y reutiliza los vectores de fragmentos sin cambios. Cada archivo o sesión se indexa en su propia transacción; un fallo se registra y se reintenta sin destruir los datos buenos anteriores.
+`recall_search` responde `{"anchors": [...], "degraded": null | "reason"}`. Cuando `degraded`
+viene establecido, el proveedor de incrustaciones estaba inalcanzable y solo se ejecutó la
+coincidencia literal — el agente puede decirlo en lugar de confundir un fallo léxico con un
+historial vacío.
 
-Las incrustaciones son intercambiables (el modelo local incluido es el predeterminado sin claves); el reranker es opcional, y el sistema se degrada elegantemente a KNN + FTS sin él. Se detecta el cambio de proveedor/modelo de incrustación y la búsqueda semántica se detiene hasta que todos los orígenes pertenezcan al mismo espacio vectorial.
+</details>
 
-## Instalación
+## Puesta en marcha rápida
 
-Dos componentes: un CLI de Python (que también incluye el servidor MCP) y un plugin que lo conecta a tu agente. Presupuesta unos dos minutos más la primera ejecución del índice.
+Dos piezas: un CLI de Python (que también incluye el servidor MCP) y un plugin que lo conecta
+a tu agente. Calcula unos dos minutos más la primera ejecución del índice.
 
-### 1. CLI
+### 1. Instala el CLI y construye el índice
 
 ```bash
 pipx install git+https://github.com/AbsoluteMode/session-recall
-session-recall index   # first run walks your whole history; later runs are incremental
+session-recall setup   # one question (interaction language), then the first index
 ```
 
-Eso es todo: sin una clave ni un servidor local, se descarga una vez el modelo ONNX incluido y luego se ejecuta en tu máquina. Consulta [Proveedores de incrustaciones](#proveedores-de-incrustaciones) para las demás opciones. Para usar las incrustaciones alojadas de Voyage, exporta una clave primero:
+No hace falta clave: sin nada configurado, la indexación corre sobre un modelo de CPU
+incluido, descargado una vez y elegido según tu idioma de interacción. La primera ejecución
+recorre todo tu historial — minutos para meses de transcripciones, segundos a partir de
+entonces. Instalaciones con script: `session-recall setup --lang en --yes`.
 
-```bash
-export VOYAGE_API_KEY=...   # voyageai.com; put the line in your shell profile
+```console
+$ session-recall index
+indexed 2175 chunks from changed transcripts
+
+your history: 1053 sessions spanning 168 days, 40,037 searchable fragments
+  Claude Code 372 · Codex 680 · Cursor 1
+  busiest: sidekey, trend_detection, glitch
 ```
 
-`pipx` coloca `session-recall` y `session-recall-mcp` en `~/.local/bin`: exactamente donde los manifiestos del plugin los buscan. La primera indexación depende de cuánto historial tengas: minutos para meses de transcripciones, segundos después.
+Las incrustaciones alojadas de Voyage clasifican notablemente mejor que el modelo incluido;
+para usarlas, exporta `VOYAGE_API_KEY` antes de indexar — consulta
+[Proveedores de incrustaciones](#proveedores-de-incrustaciones).
 
-### 2. Plugin
+### 2. Conecta tus agentes
 
-**Claude Code**
+`pipx` coloca `session-recall` y `session-recall-mcp` en `~/.local/bin` — exactamente donde
+los manifiestos de los plugins los buscan.
 
-```
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+```text
 /plugin marketplace add AbsoluteMode/session-recall
 /plugin install session-recall
 ```
 
-Luego inicia una nueva sesión: los servidores MCP y las habilidades se cargan al iniciar la sesión, no al instalar.
+Después inicia una sesión nueva — los servidores MCP, las skills y el hook SessionStart se
+cargan al arrancar la sesión, no al instalar. ¿Prefieres que el agente remate el trabajo?
+Dile `set up session-recall` (o ejecuta `/session-recall:setup`): hace las preguntas de la
+configuración inicial en el chat, ejecuta los comandos por sí mismo y termina con una
+comprobación de salud y una búsqueda real sobre tu historial.
+
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
 
-**Codex** — el manifiesto `.codex-plugin/plugin.json` está listo para colocar en un repo local o en tu marketplace personal; consulta la [local plugin installation guide](https://learn.chatgpt.com/docs/build-plugins#install-a-local-plugin-manually). Codex también te pedirá revisar los hooks recién instalados una vez mediante `/hooks`.
+El repositorio incluye un [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) nativo —
+listo para soltarlo en un repo local o en tu marketplace personal; consulta la
+[guía de instalación local de plugins](https://learn.chatgpt.com/docs/build-plugins#install-a-local-plugin-manually).
+Codex también te pide revisar una vez los hooks recién instalados mediante `/hooks`.
 
-**Cursor** — el repositorio incluye un plugin nativo con MCP, skills, comandos, subagente de recall y un hook `sessionStart` en el formato de Cursor:
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Requiere Cursor 2.5+ (ahí se introdujeron los plugins). Añade el repositorio como
+marketplace:
 
 ```bash
 cursor-agent plugin marketplace add https://github.com/AbsoluteMode/session-recall.git
 ```
 
-Después ejecuta `/add-plugin session-recall` dentro de Cursor Agent. Para desarrollo local se puede iniciar con `cursor-agent --plugin-dir /ruta/absoluta/a/session-recall`.
-Cursor muestra su aprobación habitual una sola vez para el servidor MCP stdio local; aprueba `session-recall` para iniciar las herramientas.
+Después escribe `/add-plugin session-recall` en Cursor Agent y aprueba una sola vez el
+servidor MCP stdio local, para que las herramientas puedan arrancar. Para desarrollar el
+plugin, lanza `cursor-agent --plugin-dir /absolute/path/to/session-recall` en lugar de
+instalar una copia cacheada.
+
+Cursor se detecta automáticamente en su ruta de datos habitual de macOS/Linux y no necesita
+estar en ejecución. ¿Perfil portátil o personalizado? Apunta directamente a la base de datos
+con `SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`.
+
+</details>
 
 ### 3. Comprueba que funciona
 
@@ -94,81 +213,109 @@ Cursor muestra su aprobación habitual una sola vez para el servidor MCP stdio l
 session-recall search "something you actually discussed last week"
 ```
 
-Los resultados con un `score` significan que la búsqueda semántica está activa. En el agente, `claude mcp list` debería mostrar `session-recall ✔ Connected`, y preguntarle sobre trabajo pasado debería activar `recall_search`.
-
-No hay nada más que configurar: cada plugin nativo incluye el formato de hook de su host y vuelve a indexar en segundo plano, manteniendo actualizados los tres historiales.
-
-Cursor se detecta automáticamente en su ruta de datos normal de macOS/Linux y no necesita estar abierto. Para un perfil portátil o personalizado, usa `SESSION_RECALL_CURSOR_DB=/ruta/a/User/globalStorage/state.vscdb`. Session Recall abre la base en modo de solo lectura y obtiene una copia coherente mediante la API de backup de SQLite.
-
-### Solución de problemas
+Los resultados con `score` significan que la búsqueda semántica está viva. En el agente,
+`claude mcp list` debería mostrar `session-recall ✔ Connected`, y preguntar por trabajo
+pasado debería disparar `recall_search`. No hay nada más que configurar: cada plugin incluye
+el hook de arranque de su host y reindexa en segundo plano, de modo que el índice compartido
+se mantiene al día con los tres historiales por sí solo.
 
-Empieza aquí: verifica toda la cadena y sale con código distinto de cero cuando algo está realmente roto, por lo que también funciona desde un temporizador:
-
-```console
-$ session-recall health
-[ok  ] Freshness  2 minutes behind
-[warn] Embedder   responded in 5828 ms
-                  → slow provider will make indexing crawl
-[ok  ] Vector space  builtin/BAAI/bge-small-en-v1.5/384
-[ok  ] Corpus     1054 sessions (claude 373, codex 680, cursor 1)
-[ok  ] Sources    claude, codex, cursor present
+## Cómo funciona
 
-verdict: AMBER (voyage/voyage-4-large, index at ~/.local/share/session-recall/index.db)
+```mermaid
+flowchart TB
+    subgraph Sources["local history sources"]
+      CC["Claude Code JSONL"]
+      CX["Codex JSONL"]
+      CU["Cursor SQLite"]
+    end
+
+    CC --> I["incremental indexer"]
+    CX --> I
+    CU -->|"consistent WAL snapshot"| I
+    I --> V["conversation surface → embeddings"]
+    I --> R["raw trace, kept local"]
+    V --> DB["SQLite · sqlite-vec KNN · FTS5"]
+    R --> DB
+    DB --> MCP["five on-demand MCP tools"]
+    MCP --> A["Claude Code · Codex · Cursor · any MCP client"]
 ```
 
-La frescura compara la transcripción más nueva en el disco con el turno más nuevo en el índice, por lo que un indexador que se ejecuta en cada sesión y falla cada vez sigue mostrando un retraso: que es exactamente el fallo que de otra forma sería invisible.
+Solo se incrusta la «superficie» de la conversación — los prompts del usuario y las
+respuestas de texto del asistente. Las llamadas a herramientas, los resultados, el
+razonamiento y demás datos de traza nunca se envían a un proveedor de incrustaciones, pero
+siguen accesibles bajo demanda mediante `expand_around`, `step` y `grep`. Las sidechains de
+Claude y las sesiones de subagentes lanzados se omiten a propósito: son maquinaria interna,
+no la conversación.
 
-| Síntoma | Causa |
-|---|---|
-| `recall_search` responde con `degraded` establecido | El proveedor de incrustaciones es inalcanzable: solo se ejecutó la coincidencia literal de palabras. Los resultados siguen siendo reales, pero un fallo no prueba nada. |
-| El indexador registra `HTTP code 403` con un cuerpo HTML | No es tu clave: un WAF está bloqueando tu IP (común en salidas de VPN y centros de datos). El mismo 403 aparece sin clave alguna. Redirige la salida a otro lado o cambia de proveedor. |
-| `Missing dependencies for SOCKS support` | Se ha configurado un proxy SOCKS en el entorno pero `PySocks` no está instalado en ese venv. |
-| `recent_sessions` muestra una marca de tiempo antigua | El indexador no ha tenido éxito recientemente. Ejecuta `session-recall index` manualmente y lee la salida. |
+Cursor se lee desde su almacén SQLite con la API de backup en línea, de modo que una base de
+datos WAL viva se captura de forma consistente sin bloquear el editor. Sus burbujas se
+normalizan en instantáneas JSONL duraderas y direccionadas por contenido dentro del
+directorio de datos — la navegación profunda sigue funcionando después de que Cursor se
+cierre, se actualice o se desinstale.
 
-### Referencia de CLI
+La indexación es incremental y barata sobre transcripciones vivas: son de solo añadir
+(append-only), así que los fragmentos sin cambios se emparejan por hash de contenido y sus
+vectores se reutilizan — solo los turnos nuevos llegan al proveedor de incrustaciones. Mover
+un rollout de Codex al archivo también reutiliza sus vectores. Cada archivo se indexa en su
+propia transacción; un archivo que falla se registra y se reintenta en la siguiente
+ejecución, sin abortar nunca el resto.
 
-```bash
-session-recall index --source claude|codex|cursor|all   # defaults to all
-session-recall search "query" --source codex
-session-recall recent --date 2026-07-14          # this computer's timezone
-session-recall search "deployment work" --start-date 2026-07-14 \
-  --end-date 2026-07-14 --timezone Asia/Yekaterinburg
-session-recall grep "exact" --limit 100          # raw scan, no API key needed
-session-recall prune                             # drop rows for deleted transcripts
-```
+## Referencia rápida del CLI
 
-`search`, `recent`, `grep` y `prune` aceptan un opcional `--source claude|codex|cursor`; omítelo para buscar en el historial unificado. Los filtros de fecha son inclusivos y se puede omitir cualquiera de los límites; la zona horaria predeterminada es la de esta computadora y acepta cualquier nombre IANA. `grep` se limita a 100 coincidencias por defecto.
+```bash
+# Refresh every history, or one source
+session-recall index
+session-recall index --source cursor
 
-Para desarrollo, un virtualenv dentro del árbol también funciona:
+# Semantic search — unified by default, scopable to a repo
+session-recall search "why did we choose the keeper service?"
+session-recall search "deployment work" --source codex --scope /work/keeper
 
-```bash
-python -m venv .venv && .venv/bin/pip install -e .
-.venv/bin/session-recall index
-```
+# Local calendar dates, any IANA timezone (defaults to this computer's)
+session-recall recent --date 2026-07-14
+session-recall search "deployment work" \
+  --start-date 2026-07-14 --end-date 2026-07-16 \
+  --timezone Asia/Yekaterinburg
 
-Para registrar el servidor MCP manualmente en lugar de usar el plugin:
+# Exact raw scan — no embedding call, caps at 100 matches by default
+session-recall grep "invalid_grant" --limit 100
 
-```bash
-claude mcp add session-recall --scope user -- /absolute/path/.venv/bin/session-recall-mcp
+# Housekeeping
+session-recall prune    # drop rows for transcripts deleted from disk
+session-recall health   # the whole chain, verdict GREEN/AMBER/RED
 ```
 
+`search`, `recent`, `grep` y `prune` aceptan `--source claude|codex|cursor`; omítelo para el
+historial unificado. Los filtros de fecha son inclusivos y puede omitirse cualquiera de los
+dos límites.
+
 ## Proveedores de incrustaciones
 
-Nada está atado a un solo proveedor. `SESSION_RECALL_EMBED=<preset>` establece punto de conexión, modelo, dimensión y reranker juntos, porque esos cuatro no son elecciones independientes:
+Nada está atado a un solo proveedor. `SESSION_RECALL_EMBED=<preset>` establece punto de
+conexión, modelo, dimensión y reranker a la vez, porque esas cuatro no son elecciones
+independientes:
 
-| preset | runs | model | dim | reranker |
-|---|---|---|---|---|
-| `voyage` | hosted, needs a key | `voyage-4-large` | 1024 | `rerank-2.5` |
-| `ollama` | **local, free** | `nomic-embed-text` | 768 | — |
-| `lmstudio` | **local, free** | `nomic-embed-text-v1.5` | 768 | — |
-| `openai` | hosted, needs a key | `text-embedding-3-large` | 1024 | — |
+| Preset | Ejecución | Modelo | Dim | Reranker |
+|---|---|---|---:|---|
 | `builtin-en` | **incluido, gratis** | `bge-small-en-v1.5` | 384 | — |
 | `builtin-zh` | **incluido, gratis** | `bge-small-zh-v1.5` | 512 | — |
 | `builtin-multi` | **incluido, gratis** | `paraphrase-multilingual-MiniLM-L12-v2` | 384 | — |
-
-Sin ningún preset configurado, session-recall elige Voyage cuando `VOYAGE_API_KEY` está presente, luego busca un servidor local que ya esté escuchando y, si no encuentra ninguno, usa el modelo ONNX incluido. Con una clave configurada, no se ejecuta la búsqueda local.
-
-**Gratuito y local, de principio a fin:**
+| `ollama` | **local, gratis** | `nomic-embed-text` | 768 | — |
+| `lmstudio` | **local, gratis** | `nomic-embed-text-v1.5` | 768 | — |
+| `voyage` | alojado, requiere clave | `voyage-4-large` | 1024 | `rerank-2.5` |
+| `openai` | alojado, requiere clave | `text-embedding-3-large` | 1024 | — |
+
+Sin ningún preset configurado, Session Recall elige Voyage cuando `VOYAGE_API_KEY` está
+presente, después sondea si ya hay un servidor local escuchando y, si no, ejecuta el modelo
+ONNX incluido — lo de serie siempre funciona. La variante incluida sigue el idioma de
+interacción que elegiste en la configuración inicial (`SESSION_RECALL_LANG=en|zh|…`: un
+pequeño especialista en inglés o en chino, multilingüe en el resto de casos). El primer uso
+descarga el modelo una vez al directorio de datos (70–240 MB); desde entonces, inferencia en
+CPU. La clasificación es notablemente más gruesa que la de Voyage alojado — un punto de
+partida, no el techo. Los presets locales no incluyen reranker, así que la clasificación es
+solo KNN + FTS.
+
+**Gratis y local, de principio a fin:**
 
 ```bash
 ollama pull nomic-embed-text
@@ -176,7 +323,9 @@ export SESSION_RECALL_EMBED=ollama
 session-recall index
 ```
 
-**Tu propio punto de conexión** — cualquier servidor que hable `/v1/embeddings` (llama.cpp, vLLM, una puerta de enlace corporativa). Las variables individuales siempre prevalecen sobre el preset, así que mezcla libremente:
+**Tu propio punto de conexión** — cualquier servidor que hable `/v1/embeddings` (llama.cpp,
+vLLM, una puerta de enlace corporativa). Las variables individuales siempre ganan al preset,
+así que mezcla con libertad:
 
 ```bash
 export SESSION_RECALL_EMBED_PROVIDER=openai-compatible
@@ -185,18 +334,36 @@ export SESSION_RECALL_EMBED_MODEL=your-model
 export SESSION_RECALL_EMBED_DIM=1024
 ```
 
-Dos cosas que vale la pena saber antes de cambiar:
+**Un embedder distinto necesita su propio índice.** Las tablas vectoriales son de ancho
+fijo, así que cambiar el modelo o la dimensión implica reconstruir: borra
+`~/.local/share/session-recall/index.db` y vuelve a ejecutar `index`. Session Recall toma la
+huella del espacio de incrustaciones de cada archivo indexado y se niega a mezclar espacios —
+la búsqueda semántica se apaga con un mensaje explícito en lugar de devolver clasificaciones
+engañosas.
+
+<details>
+<summary><strong>Notas sobre licencias de modelos</strong></summary>
 
-- **Un embedder diferente necesita su propio índice.** Las tablas vectoriales tienen ancho fijo, por lo que cambiar el modelo o la dimensión significa reconstruir: elimina `~/.local/share/session-recall/index.db` y vuelve a ejecutar `index`. Intentar reutilizar el antiguo ahora falla con un mensaje que dice exactamente eso, en lugar de parecer un embedder muerto.
-- **Los presets locales no incluyen reranker**, por lo que la clasificación es solo KNN + FTS: suficiente, pero notablemente más gruesa que la ruta alojada.
+`nomic-embed-text` es el predeterminado local porque es Apache-2.0 y se instala con un solo
+comando. Existen modelos pequeños más fuertes — `jina-embeddings-v5-text-nano` puntúa
+muchísimo mejor para su tamaño — pero son **CC BY-NC**, algo que cualquiera que indexe
+historial de trabajo estaría violando sin que nadie se lo dijera. Si tu uso es genuinamente
+no comercial, apunta las variables de arriba a uno de ellos. Si trabajas en más idiomas que
+el inglés, `qwen3-embedding:0.6b` (Apache-2.0) maneja el historial multilingüe bastante
+mejor que `nomic`.
 
-Sobre la elección del modelo: `nomic-embed-text` es el predeterminado porque es Apache-2.0 e instala en un solo comando. Existen modelos pequeños más potentes: `jina-embeddings-v5-text-nano` puntúa mucho más alto para su tamaño, pero son **CC BY-NC**, lo que cualquiera que indexe historial de trabajo violaría sin que nunca se lo digan. Si tu uso es genuinamente no comercial, apunta las variables anteriores a uno de ellos. Si trabajas en más idiomas que el inglés, `qwen3-embedding:0.6b` (Apache-2.0) maneja el historial multilingüe mucho mejor que `nomic`.
+</details>
 
 ## Mantener el índice actualizado
 
-Si instalaste el plugin, esto ya está manejado: pasa a la siguiente sección. El hook `SessionStart` incluido ejecuta `session-recall index` en segundo plano, y el `--source all` predeterminado actualiza Claude, Codex y Cursor. La indexación es incremental, por lo que mantenerse al día es económico.
+Si instalaste un plugin, esto ya está resuelto: el hook `SessionStart` incluido ejecuta
+`session-recall index` en segundo plano en cada arranque de sesión, y la indexación
+incremental lo mantiene barato.
 
-Solo si registraste el servidor MCP manualmente, añade el hook tú mismo en `~/.claude/settings.json`:
+<details>
+<summary><strong>¿Registraste el servidor MCP a mano? Añade el hook tú mismo</strong></summary>
+
+En `~/.claude/settings.json`:
 
 ```json
 "hooks": {
@@ -209,32 +376,239 @@ Solo si registraste el servidor MCP manualmente, añade el hook tú mismo en `~/
 }
 ```
 
-La guardia `pgrep` previene ejecuciones superpuestas; `(\` … \`& )\` se desacopla para que el inicio de sesión no espere. Mantén el hook a nivel de host síncrono: el shell ya envía el indexador a segundo plano, y Codex ignora la extensión `async` de Claude. Un temporizador `launchd`/cron es otra opción. (Local en una máquina es suficiente; un índice del lado del servidor solo tiene sentido en varias máquinas: a costa de la privacidad y la red.)
+La guarda `pgrep` evita ejecuciones solapadas; `( … & )` se desacopla para que el arranque de
+sesión no espere. Mantén síncrono el hook a nivel de host — el shell ya manda el indexador a
+segundo plano, y Codex ignora la extensión `async` de Claude. Un temporizador `launchd`/cron
+también sirve.
+
+</details>
 
-## meta docs — la memoria del proyecto, escrita
+## Modo equipo — pregunta al historial de un colega
 
-El recordatorio raw responde a "qué se dijo". meta docs responde a las preguntas que los agentes hacen realmente a mitad de tarea: *¿se arregló este error antes? ¿cómo realizo esta acción? ¿por qué se decidió de esta manera?* Un trabajo diario destila el diálogo de cada sesión — solo mensajes del usuario y respuestas finales, nunca el ruido de las herramientas — en documentos vivos dentro de un repositorio git de tu elección:
+El mismo recall, entre máquinas: emparéjate una vez con un colega y tu agente podrá
+preguntarle al suyo por su trabajo pasado.
 
-- `<project>/bugs.md` — errores que se arreglaron realmente: cómo se reconoció, diagnosticó, arregló y demostró que estaba arreglado cada uno;
-- `<project>/actions.md` — procedimientos, paso a paso, escritos para que un agente consultado de nuevo pueda seguir la entrada solo;
-- `<project>/decisions.md` — decisiones controvertidas: qué se decidió, por qué así, qué se rechazó;
-- `USER.md` — un mapa de dónde vive tu información y *cómo encontrarla* (comandos de búsqueda, ubicaciones de almacenamiento — nunca los valores almacenados en sí).
+> **tú → el agente de un colega:** cuando te topaste con el problema del arranque en local
+> de X — ¿cómo lo resolviste?
+>
+> **su agente** *(después de que el colega apruebe la respuesta)*: fija la configuración en
+> …, luego …, y el problema no vuelve a aparecer.
+
+Lo que antes era un hilo de Slack y una explicación recordada a medias se convierte en una
+pregunta y una respuesta fundamentada. Nunca ves el historial en bruto del colega — solo la
+respuesta que aprobó.
+
+Aquí la privacidad es mecánica, no política:
+
+- las preguntas y las respuestas viajan como **sobres cifrados de extremo a extremo**; el
+  relay almacena blobs ciegos que no puede leer;
+- las respuestas las construye un **worker aislado de solo lectura**, acotado a los proyectos
+  concedidos explícitamente a ese contacto (`share allow`);
+- cada respuesta candidata pasa por un **escáner de secretos** y después por la **aprobación
+  explícita del dueño** (bot de Telegram, o `share approve` en local) antes de salir de la
+  máquina;
+- un contacto puede pausarse en cualquier momento (`share pause`) y un peer puede revocarse
+  (`share revoke`).
+
+Buscar en el índice de un peer no exige configurar incrustaciones de tu lado: la consulta
+viaja como texto, y el worker del dueño la incrusta con su propio proveedor contra su propio
+índice.
+
+<details>
+<summary><strong>Elige un transporte (una vez, antes del emparejamiento)</strong></summary>
+
+Una instalación recién hecha **no tiene transporte** y nunca habla con un servidor que no
+hayas elegido. El relay es ciego — todo lo que transporta se sella y se firma en los
+clientes — así que cuál usar es coordinación entre peers, no una cuestión de confianza.
+
+**Carpeta compartida — cero infraestructura.** Dos cuentas en una misma máquina, o cualquier
+carpeta que ambos peers sincronicen (Syncthing, Dropbox, un montaje NFS):
+
+```bash
+export SESSION_RECALL_SHARE_TRANSPORT_DIR=~/Sync/sr-share   # both peers, same folder
+```
+
+**Tu relay en la LAN.** Una máquina lo ejecuta y todos apuntan a ella. Los sobres van
+cifrados de extremo a extremo en cualquier caso, pero esto es HTTP plano — resérvalo para
+una red en la que confíes:
+
+```bash
+session-recall share relay --port 8787 --host 0.0.0.0       # on the relay machine
+export SESSION_RECALL_RELAY_URL=http://192.168.1.20:8787    # on every peer
+```
+
+**Tu relay en internet.** El relay se liga a localhost a propósito y espera un terminador
+TLS delante (Caddy es la opción de dos líneas):
 
 ```bash
-session-recall metadocs init ~/meta-docs            # every git project; or --projects name…
-session-recall metadocs run                         # one pass now
-session-recall metadocs enable                      # daily launchd job (default 21:00)
+session-recall share relay --port 8787    # binds 127.0.0.1
+```
+
+```text
+relay.example.com {
+    reverse_proxy 127.0.0.1:8787
+}
+```
+
+Después, en cada peer: `export SESSION_RECALL_RELAY_URL=https://relay.example.com`. El relay
+solo almacena blobs sellados, y cada buzón se vacía al recogerlo.
+`SESSION_RECALL_RELAY_URL=none` mantiene una instalación en silencio de red a propósito. Pon
+el `export` en tu perfil de shell para que los agentes y los temporizadores también lo vean.
+
+</details>
+
+<details>
+<summary><strong>Emparejar y preguntar</strong></summary>
+
+El emparejamiento es una ceremonia de una sola vez con una breve verificación SAS; después,
+preguntar es un solo comando:
+
+```bash
+session-recall share init            # once per device, both sides
+session-recall share invite          # you: prints a one-time code
+session-recall share join <code>     # colleague: accepts it
+session-recall share complete        # you: finish the handshake
+session-recall share trust <name>    # both: confirm the SAS matched, name the peer
+session-recall share allow <name> <project>
+session-recall share notify          # owner side: worker + approval loop
+
+session-recall share ask <name> "how did you fix the local X launch?"
+session-recall share fetch           # collect the answers
+```
+
+</details>
+
+## Meta docs — la memoria del proyecto, puesta por escrito
+
+El recall en bruto responde a *qué se dijo*. Meta docs responde a lo que los agentes
+preguntan de verdad en mitad de una tarea: *¿este bug ya se arregló antes? ¿cómo realizo
+esta acción? ¿por qué se decidió así?* Un trabajo diario entrega el diálogo de cada sesión —
+mensajes del usuario y respuestas finales, nunca el ruido de las herramientas — a un agente
+destilador que mantiene entradas en Markdown dentro de un repositorio Git que tú eliges:
+
+- `<project>/bugs/` — bugs que de verdad se arreglaron: cómo se reconoció, diagnosticó,
+  arregló y demostró arreglado cada uno;
+- `<project>/actions/` — procedimientos, paso a paso, escritos para que un agente al que se
+  le pregunte de nuevo pueda seguir la entrada por sí solo;
+- `<project>/decisions/` — decisiones disputadas: qué se decidió, por qué así, qué se
+  rechazó;
+- `USER/` — un mapa global de dónde vive tu información y *cómo encontrarla* (comandos de
+  consulta y ubicaciones de almacenamiento — nunca los valores almacenados en sí).
+
+```bash
+session-recall metadocs init ~/meta-docs --from-today   # memory starts now
+session-recall metadocs run                             # one pass now
+session-recall metadocs enable   # daily job: launchd (macOS) / systemd user timer (Linux)
 session-recall metadocs status
+session-recall metadocs index-history --days 30         # opt-in: distill the past, once
+```
+
+Todo el mundo del destilador son cuatro verbos MCP — `search / create / edit / delete` — y
+las reglas que soportan la carga son mecánica del servidor, no peticiones en el prompt:
+`create` se rechaza hasta que el agente haya hecho `search` (la deduplicación es
+obligatoria), las entradas se escanean en busca de secretos antes de que un solo byte llegue
+al disco, y `delete` exige un motivo. Las ejecuciones son incrementales y cada proyecto con
+cambios recibe su propio commit local — revisar es un diff, deshacer es un revert, y
+compartir la memoria con un equipo es simplemente subir el repo a algún lugar privado. Nada
+se sube a menos que actives `--push`; el motor y el modelo salen solo de la configuración
+(`init --engine claude-cli|codex --model …`) — nada se elige en silencio.
+
+## La privacidad es una invariante estricta
+
+Este es un repositorio público. **En él solo entra código.** Los datos de ejecución viven
+bajo `~/.local/share/session-recall/`, fuera del árbol del repo — físicamente no pueden
+acabar en un commit.
+
+| Se queda en tu máquina | Sale solo cuando tú lo decides |
+|---|---|
+| Las transcripciones originales de Claude Code y Codex | El texto de superficie de la conversación → el embedder alojado que configures |
+| El almacén SQLite de Cursor y sus instantáneas normalizadas | Una respuesta del modo equipo aprobada explícitamente |
+| Llamadas a herramientas, salidas, razonamiento — toda la traza en bruto | Nada, en la ruta de incrustación incluida/local |
+| El índice SQLite y los vectores almacenados | |
+
+- Las claves de API son solo variables de entorno; `.gitignore` bloquea `.env`.
+- Las pruebas usan fixtures sintéticos, nunca un trozo real de una sesión.
+- El proveedor incluido mantiene toda la ruta de indexación en el dispositivo. Si eliges un
+  proveedor alojado, elige uno al que confiarías el texto de superficie de tus
+  transcripciones.
+
+## Solución de problemas
+
+Empieza aquí — comprueba toda la cadena y sale con código distinto de cero cuando algo está
+roto de verdad, así que también funciona desde un temporizador:
+
+```console
+$ session-recall health
+[ok  ] Freshness  2 minutes behind
+[warn] Embedder   responded in 5828 ms
+                  → slow provider will make indexing crawl
+[ok  ] Vector space  builtin/BAAI/bge-small-en-v1.5/384
+[ok  ] Corpus     1054 sessions (claude 373, codex 680, cursor 1)
+[ok  ] Sources    claude, codex, cursor present
+
+verdict: AMBER (voyage/voyage-4-large, index at ~/.local/share/session-recall/index.db)
 ```
 
-Las ejecuciones son incrementales (marcas de agua por sesión), el destilador es una llamada `claude -p` enjaulada sin todas las herramientas, cada documento se escanea en busca de secretos antes de escribirse (un documento marcado se bloquea, no se enmascara), y cada ejecución termina en un commit git — la revisión es un diff, deshacer es un revert, y compartir la memoria con un equipo es simplemente enviar el repo a algún lugar privado. Los commits permanecen locales a menos que optes por `--push`.
+La frescura compara la transcripción más nueva en disco con el turno más nuevo del índice,
+así que un indexador que se ejecuta en cada sesión y falla todas las veces sigue apareciendo
+retrasado — exactamente el fallo que de otro modo resulta invisible.
+
+| Síntoma | Causa / siguiente paso |
+|---|---|
+| `recall_search` responde con `degraded` establecido | El proveedor de incrustaciones está inalcanzable — solo se ejecutó la coincidencia literal. Los resultados son reales, pero un fallo no demuestra nada. |
+| `degraded` dice "embedder changed" | El índice se construyó en otro espacio de incrustaciones. Ejecuta `session-recall index` para reincrustar; hasta entonces la clasificación semántica queda apagada, a propósito. |
+| El indexador registra `HTTP code 403` con un cuerpo HTML | No es tu clave: un WAF está bloqueando tu IP (habitual en salidas de VPN y de centros de datos). El mismo 403 aparece incluso sin clave. Enruta la salida por otro lado o cambia de proveedor. |
+| `Missing dependencies for SOCKS support` | Hay un proxy SOCKS configurado en el entorno, pero `PySocks` no está instalado en ese venv. |
+| `recent_sessions` muestra una marca de tiempo antigua | El indexador no ha terminado bien últimamente. Ejecuta `session-recall index` a mano y lee la salida. |
+| Cursor vive en un perfil personalizado | Define `SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`. |
 
-## Privacidad — invariante estricta
+## Desarrollo
 
-Este es un repositorio público. **Solo entra código en él.**
+```bash
+git clone https://github.com/AbsoluteMode/session-recall.git
+cd session-recall
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest -q
+```
+
+Para registrar el servidor MCP a mano en lugar de usar el plugin:
+
+```bash
+claude mcp add session-recall --scope user -- /absolute/path/.venv/bin/session-recall-mcp
+```
 
-- Datos, índices, transcripciones raw, incrustaciones → `~/.local/share/session-recall/`, **fuera del árbol del repo**. Físicamente no pueden ser commitados.
-- Claves API → solo en el entorno (`VOYAGE_API_KEY`); `.gitignore` bloquea `.env`.
-- Pruebas → solo fixtures sintéticos, nunca una porción real de una sesión.
-- Las transcripciones de Claude Code, las transcripciones activas y archivadas de Codex y el SQLite de Cursor se leen localmente. Las instantáneas normalizadas de Cursor permanecen en el directorio de datos. Solo el texto superficial de usuario/asistente se incrusta; las herramientas y el razonamiento quedan fuera de las incrustaciones.
-- Los textos de los fragmentos se envían al proveedor configurado. Sin claves, el proveedor incluido permanece completamente local; si eliges Voyage u otro endpoint alojado, usa uno en el que confíes.
+La justificación de ingeniería y las invariantes viven en [`docs/decisions/`](docs/decisions/).
+Empieza por:
+
+- [Índice unificado de Claude Code + Codex](docs/decisions/2026-07-10-unified-claude-codex-index.md)
+- [Cursor como origen en bruto duradero](docs/decisions/2026-08-03-cursor-durable-raw-source.md)
+- [Recall acotado por proyecto](docs/decisions/2026-06-26-recall-project-scope.md)
+- [Puerta de seguridad de la compartición P2P](docs/decisions/2026-07-30-p2p-sharing-v1-security-gate.md)
+- [Meta docs, memoria viva del proyecto](docs/decisions/2026-07-31-metadocs-living-project-memory.md)
+
+## Hoja de ruta
+
+- **Índice alojado/de equipo** — un índice compartido para todo el equipo en lugar de copias
+  por máquina. La pregunta abierta honesta: quien busca debe incrustar la consulta, así que
+  un espacio vectorial compartido implica una ruta de incrustación compartida.
+- **Omitir la aprobación por contacto** — saltarse la aprobación por respuesta con los peers
+  en los que confías plenamente; hoy cada respuesta se aprueba explícitamente.
+- **Más historiales** — transcripciones de otros agentes más allá de Claude Code, Codex y
+  Cursor.
+
+## Contribuir
+
+Los issues, las mejoras de documentación, los adaptadores de hosts y las traducciones son
+bienvenidos. Mantén los fixtures sintéticos y nunca incluyas en un commit transcripciones
+reales, índices, incrustaciones ni credenciales.
+
+<div align="center">
+  <br />
+  <strong>Deja de reconstruir el contexto. Continúalo.</strong>
+  <br />
+  <br />
+  <a href="#puesta-en-marcha-rápida">Empieza ahora</a>
+  &nbsp;·&nbsp;
+  <a href="LICENSE">Licencia MIT</a>
+</div>
diff --git a/README.md b/README.md
index 0be748b..dbf65aa 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,39 @@
-# session-recall
+<div align="center">
 
-*Русская версия: [docs/README.ru.md](docs/README.ru.md) · Español:
-[README.es-ES.md](README.es-ES.md) (community translation)*
+<a href="#quick-start">
+  <img src="assets/og.webp" alt="Session Recall — your coding agents forget, Session Recall doesn't. One memory for Claude Code, Codex, and Cursor." width="100%" />
+</a>
 
-**Shared memory for Claude Code, Codex, and Cursor.** Pick up work from a month ago without
-re-explaining it — and Claude can read what Codex or Cursor worked out yesterday, because all
-three feed one index. Not a summary file someone maintains by hand: the actual turns, including tool
-calls and reasoning, searchable by meaning.
+<br />
+<br />
 
-```console
-$ session-recall index
-indexed 2175 chunks from changed transcripts
+<strong>Shared semantic memory for Claude Code, Codex, and Cursor.</strong><br />
+Find an old decision by meaning. Open the raw evidence. Continue the work.
 
-your history: 1053 sessions spanning 168 days, 40,037 searchable fragments
-  Claude Code 372 · Codex 680 · Cursor 1
-  busiest: sidekey, trend_detection, glitch
-```
+<br />
+<br />
+
+[![MIT License](https://img.shields.io/badge/license-MIT-b8f84f?style=flat-square&labelColor=11120f)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-b8f84f?style=flat-square&labelColor=11120f)](pyproject.toml)
+[![MCP native](https://img.shields.io/badge/MCP-native-b8f84f?style=flat-square&labelColor=11120f)](src/session_recall/server.py)
+[![Tests](https://img.shields.io/github/actions/workflow/status/AbsoluteMode/session-recall/test.yml?branch=main&style=flat-square&label=tests&labelColor=11120f)](https://github.com/AbsoluteMode/session-recall/actions/workflows/test.yml)
+
+<br />
 
-Then your agent stops asking you what you were doing:
+English · [Русский](docs/README.ru.md) · [Español](README.es-ES.md) · [中文](README.zh-CN.md)
+
+</div>
+
+---
+
+Your coding agents remember the current chat. Your work lives across months of chats —
+resumed sessions, parallel subscriptions, worktrees, different agents.
+
+Session Recall turns that history into one local-first index and serves it back through
+five focused MCP tools. A fresh session can recover what Codex worked out yesterday and
+what Claude Code rejected three months ago — with links back to the actual turns, tool
+output, and reasoning. Not a summary file someone maintains by hand: the original
+conversation stays the source of truth.
 
 > **you:** we were fixing the auth token conflict between the two services — where did we land?
 >
@@ -26,151 +42,158 @@ Then your agent stops asking you what you were doing:
 > rejected the shared-credentials-directory patch as too coupled, and settled on a keeper service
 > owning the session. The spec was never written — that was the next step.
 
-## Where it pays off
+## What you get
 
-Two months of daily use; the cases that stuck:
+| | Capability | What it changes |
+|---|---|---|
+| **One memory** | Claude Code, Codex, and Cursor feed the same index | Switch agents without resetting the project story |
+| **Semantic retrieval** | Search by meaning, not only exact words | Recover decisions you can describe but cannot quote |
+| **Deep navigation** | Open raw turns: tool calls, outputs, reasoning | Verify the answer instead of trusting a summary |
+| **Honest degradation** | A semantic outage is reported explicitly | A literal-only fallback never poses as semantic search |
+| **Local by default** | Bundled ONNX embeddings and local SQLite | Start without a key, a server, or an account |
+| **Scoped recall** | Filter by repo, source, or local calendar dates | Keep unrelated projects out of the answer |
+| **Team answers** | Ask a colleague's local memory, owner-approved | Share hard-won context without exposing raw sessions |
+
+## Where it pays off
 
 - **Session onboarding.** A fresh session starts already in context — whether you juggle
-  several subscriptions, hop between coding agents (Claude reads what Codex worked out
-  yesterday), brainstorm the same problem across parallel sessions, or return to a task
-  you "discussed at some point".
-- **Bugs and regressions.** Before fixing anything, the agent asks the history: *was this
-  bug seen before? how was it fixed? why did we believe it was fixed?* A recurrence you
-  yourself forgot stops looking like a fresh bug — and the fix turns from a patch into a
-  dig into the component.
-- **Actions.** Explain a procedure once — how to read a trace, fill your work
-  spreadsheets, break down token spend per task per model — and any later session
-  replays it without being walked through again.
-- **Cause and effect.** Say "let's change this decision", and the agent looks up the
-  moment it was made: *"we picked X for compatibility with Y — before changing anything,
-  make sure Y survives."*
-
-Five tools over MCP:
-
-- `recall_search(query)` — find a past discussion **by meaning** (not substring). Answers
-  `{"anchors": [...], "degraded": null | str}`; `degraded` is set when the embedding provider was
-  unreachable and only literal matching ran, so the agent can say so instead of mistaking a
-  lexical miss for an empty history.
-- `expand_around(session_id, uuid)` — a cursor into the raw turn (tool calls, outputs, thinking).
-- `step(session_id, uuid, direction)` — move to an adjacent turn (cheap cursor step).
-- `grep(pattern)` — on-demand substring scan over **all** indexed transcripts, including
-  under-the-hood turns (tool output, thinking) that never became search chunks.
-- `recent_sessions()` — the freshest past sessions first (what's current, how fresh the index is).
-
-On-demand (no proactive auto-injection in v1). Local, open source. The tools are plain
-MCP, so any MCP-capable agent can search the same history; the histories being
-indexed today come from Claude Code, Codex, and Cursor.
-
-`recall_search`, `grep` and `recent_sessions` also take an optional `scope_cwd` — pass your
-current working directory to scope results to the current repo (worktrees collapse to the repo
-root); omit it for cross-project recall. Ranked hits carry a human-readable `when_human`
-timestamp alongside the raw epoch. Every MCP tool accepts an optional `source` (`claude`,
-`codex`, or `cursor`); omit it to use the unified history. Results include provenance such as
-`source=claude`, `source=codex`, or `source=cursor`. The three discovery tools also accept `on_date` for one day or inclusive
-`start_date` / `end_date` (`YYYY-MM-DD`) plus an optional IANA `timezone`, so an agent can
-constrain retrieval to an actual local calendar day instead of hoping a date written into the
-semantic query affects ranking. If `timezone` is omitted, Session Recall uses the timezone of
-the computer running the MCP server.
-
-**Status:** v1, built and validated on real history. Key design rationale lives in
-[docs/decisions/](docs/decisions/).
+  several subscriptions, hop between agents, or return to a task you "discussed at some point".
+- **Bugs and regressions.** Before fixing anything, the agent asks the history: *was this bug
+  seen before? how was it fixed? why did we believe it was fixed?* A recurrence stops looking
+  like a fresh bug — and the fix turns from a patch into a dig into the component.
+- **Procedures.** Explain a workflow once — how to read a trace, how to break down token
+  spend per task — and any later session replays it without being walked through again.
+- **Cause and effect.** Say "let's change this decision", and the agent looks up the moment it
+  was made: *"we picked X for compatibility with Y — before changing anything, make sure Y
+  survives."*
 
-## How it works
+## Five tools, one workflow
 
-Claude Code transcripts, Codex sessions from `~/.codex/sessions` plus
-`~/.codex/archived_sessions`, and Cursor sessions (read from its SQLite store,
-`User/globalStorage/state.vscdb`; subagent sessions skipped, workspaces mapped
-to projects) share the same index. Cursor bubbles are normalized into durable,
-content-addressed JSONL snapshots under the session-recall data directory, so
-raw navigation keeps working after Cursor closes, upgrades, or is uninstalled.
-Only the conversation "surface" is embedded — user prompts and assistant text replies.
-Tool calls, results, reasoning, and other trace data are not embedded but stay reachable on
-demand via `expand_around` (and `step`) or `grep`. Original Claude/Codex transcripts and
-Cursor's normalized raw snapshots remain local; only the extracted conversation surface is
-sent to the configured embedding provider.
-
-The zero-config path is a language-aware bundled ONNX model → SQLite
-(`sqlite-vec` KNN + FTS5, bm25-ranked) → top-k. With a Voyage key the higher-quality
-hosted path is `voyage-4-large` (dim 1024) → SQLite → `rerank-2.5`. Indexing is
-incremental (by file metadata, including Codex inode+size) and cheap on live transcripts: they are append-only, so
-unchanged chunks are matched by content hash and their vectors reused — only new turns
-hit the embedding API. Moving a Codex rollout into the archive also reuses its existing
-vectors. Each file indexes in its own transaction; a failing file is
-logged and retried on the next run, never aborting the rest. Claude sidechains
-(`<session>/subagents/`) and Codex spawned-subagent sessions are intentionally skipped —
-they are under-the-hood tooling, not the primary user/agent conversation.
-
-Embeddings are pluggable (the bundled local model is the no-key default); the reranker is optional, and the
-system degrades gracefully to KNN + FTS without one. Switching the embedding
-provider/model is detected (an embed fingerprint is part of each file's index
-signature) and triggers a clean re-embed instead of silently mixing vector spaces.
-
-## Install
-
-Two pieces: a Python CLI (which also ships the MCP server) and a plugin that wires it into your
-agent. Budget about two minutes plus the first index run.
-
-### 1. CLI
+The interface stays deliberately small:
+
+| MCP tool | Use it when |
+|---|---|
+| `recall_search(query)` | You remember the idea, not the wording |
+| `expand_around(session_id, uuid)` | You found an anchor and need the surrounding evidence |
+| `step(session_id, uuid, direction)` | You need the adjacent raw turn without another search |
+| `grep(pattern)` | You know an exact error, symbol, path, or identifier |
+| `recent_sessions()` | You want the freshest work — and the index freshness |
+
+```mermaid
+flowchart LR
+    Q["describe the old problem"] --> S["recall_search"]
+    S --> A["ranked anchor"]
+    A --> E["expand_around"]
+    E --> T["step next / prev"]
+    Q -. exact identifier .-> G["grep"]
+    R["what is current?"] --> RS["recent_sessions"]
+```
+
+Every discovery tool accepts an optional `source` (`claude` | `codex` | `cursor`), a
+`scope_cwd` to narrow results to the current repo (worktrees collapse to the repo root), and
+local calendar dates (`on_date`, or `start_date` / `end_date`, plus an IANA `timezone`).
+Ranked anchors carry provenance and a human-readable timestamp. `grep` scans **all** indexed
+transcripts on demand — including under-the-hood turns (tool output, thinking) that never
+became search chunks. On-demand only: no proactive context injection into every prompt.
+
+<details>
+<summary><strong>See a complete call</strong></summary>
+
+```json
+{
+  "query": "why did refresh tokens conflict?",
+  "scope_cwd": "/work/keeper",
+  "source": "codex",
+  "start_date": "2026-05-01",
+  "end_date": "2026-06-30",
+  "timezone": "Europe/Moscow"
+}
+```
+
+`recall_search` answers `{"anchors": [...], "degraded": null | "reason"}`. When `degraded`
+is set, the embedding provider was unreachable and only literal matching ran — the agent can
+say so instead of mistaking a lexical miss for an empty history.
+
+</details>
+
+## Quick start
+
+Two pieces: a Python CLI (which also ships the MCP server) and a plugin that wires it into
+your agent. Budget about two minutes plus the first index run.
+
+### 1. Install the CLI and build the index
 
 ```bash
 pipx install git+https://github.com/AbsoluteMode/session-recall
 session-recall setup   # one question (interaction language), then the first index
 ```
 
-`setup` is optional sugar — `session-recall index` directly works too, every
-setting has a default. The first run walks your whole history; later runs are
-incremental. Scripted installs: `session-recall setup --lang en --yes`.
+No key required: with nothing configured, indexing runs on a bundled CPU model, downloaded
+once and picked by your interaction language. The first run walks your whole history —
+minutes for months of transcripts, seconds after that. Scripted installs:
+`session-recall setup --lang en --yes`.
 
-That is the whole thing: with no key and no local server, indexing runs on a
-bundled CPU model, downloaded once and picked by your interaction language
-(`SESSION_RECALL_LANG=en|zh|…`, multilingual when unset) — see
-[Embedding providers](#embedding-providers) for the options. Hosted Voyage
-embeddings rank noticeably better; to use them instead, export a key first:
+```console
+$ session-recall index
+indexed 2175 chunks from changed transcripts
 
-```bash
-export VOYAGE_API_KEY=...   # voyageai.com; put the line in your shell profile
+your history: 1053 sessions spanning 168 days, 40,037 searchable fragments
+  Claude Code 372 · Codex 680 · Cursor 1
+  busiest: sidekey, trend_detection, glitch
 ```
 
-`pipx` puts `session-recall` and `session-recall-mcp` on `~/.local/bin` — exactly where the
-plugin manifests look for them. The first index depends on how much history you have: minutes
-for months of transcripts, seconds after that.
+Hosted Voyage embeddings rank noticeably better than the bundled model; to use them, export
+`VOYAGE_API_KEY` before indexing — see [Embedding providers](#embedding-providers).
 
-### 2. Plugin
+### 2. Connect your agents
 
-**Claude Code**
+`pipx` puts `session-recall` and `session-recall-mcp` on `~/.local/bin` — exactly where the
+plugin manifests look for them.
 
-```
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+```text
 /plugin marketplace add AbsoluteMode/session-recall
 /plugin install session-recall
 ```
 
-Then start a new session — MCP servers and skills load at session start, not on install.
+Then start a new session — MCP servers, skills, and the SessionStart hook load at session
+start, not on install. Prefer to let the agent finish the job? Say `set up session-recall`
+(or run `/session-recall:setup`): it asks the onboarding questions in chat, runs the
+commands itself, and ends with a health check and a real search over your history.
 
-Prefer to let the agent do the setup? After installing the plugin, say
-"set up session-recall" (or run `/session-recall:setup`): the agent asks the
-three onboarding questions in chat — language, local or cloud embedder,
-solo or team — runs the commands itself, and finishes with a health check
-and a real search over your history.
+</details>
 
-**Codex** — the `.codex-plugin/plugin.json` manifest is ready to drop into a local repo or your
-personal marketplace; see the
+<details>
+<summary><strong>Codex</strong></summary>
+
+The repository ships a native [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) —
+ready to drop into a local repo or your personal marketplace; see the
 [local plugin installation guide](https://learn.chatgpt.com/docs/build-plugins#install-a-local-plugin-manually).
 Codex also asks you to review newly installed hooks once via `/hooks`.
 
-**Cursor** — this repository also ships a native `.cursor-plugin/plugin.json`, Cursor-format
-MCP and hook configs, and the same skills/commands/recall subagent. Add the repository as a
-marketplace, then install the plugin in Cursor:
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Requires Cursor 2.5+ (plugins were introduced there). Add the repository as a marketplace:
 
 ```bash
 cursor-agent plugin marketplace add https://github.com/AbsoluteMode/session-recall.git
 ```
 
-Then type `/add-plugin session-recall` in Cursor Agent. This requires Cursor 2.5+ (plugins were
-introduced there). The plugin exposes the five recall tools to Cursor and its `sessionStart`
-hook refreshes Claude Code, Codex, and Cursor history together. For local development, launch
-`cursor-agent --plugin-dir /absolute/path/to/session-recall` instead of installing a cached copy.
-Cursor shows its normal one-time approval for the local stdio MCP server; approve
-`session-recall` so the tools can start.
+Then type `/add-plugin session-recall` in Cursor Agent and approve the local stdio MCP
+server once, so the tools can start. For plugin development, launch
+`cursor-agent --plugin-dir /absolute/path/to/session-recall` instead of installing a
+cached copy.
+
+Cursor is auto-detected at its normal macOS/Linux data path and does not need to be
+running. Portable or custom profile? Point at the database directly with
+`SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`.
+
+</details>
 
 ### 3. Check it works
 
@@ -178,101 +201,100 @@ Cursor shows its normal one-time approval for the local stdio MCP server; approv
 session-recall search "something you actually discussed last week"
 ```
 
-Hits with a `score` mean semantic search is live. In the agent, `claude mcp list` should show
-`session-recall ✔ Connected`, and asking it about past work should trigger `recall_search`.
-
-Nothing else to configure: each native plugin ships the host's startup-hook format and re-indexes
-in the background, so the shared index keeps up with all three histories on its own.
-
-Cursor is auto-detected at its normal macOS/Linux data path and does not need to be running.
-If you use a portable or custom Cursor profile, point directly at its database with
-`SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`. Session Recall opens it
-read-only and uses SQLite's backup API, so a live WAL database is read consistently without
-blocking the editor.
-
-### Troubleshooting
-
-Start here — it checks the whole chain and exits non-zero when something is actually
-broken, so it also works from a timer:
+Hits with a `score` mean semantic search is live. In the agent, `claude mcp list` should
+show `session-recall ✔ Connected`, and asking about past work should trigger
+`recall_search`. Nothing else to configure: each plugin ships its host's startup hook and
+re-indexes in the background, so the shared index keeps up with all three histories on its
+own.
 
-```console
-$ session-recall health
-[ok  ] Freshness  2 minutes behind
-[warn] Embedder   responded in 5828 ms
-                  → slow provider will make indexing crawl
-[ok  ] Vector space  builtin/BAAI/bge-small-en-v1.5/384
-[ok  ] Corpus     1054 sessions (claude 373, codex 680, cursor 1)
-[ok  ] Sources    claude, codex, cursor present
+## How it works
 
-verdict: AMBER (voyage/voyage-4-large, index at ~/.local/share/session-recall/index.db)
+```mermaid
+flowchart TB
+    subgraph Sources["local history sources"]
+      CC["Claude Code JSONL"]
+      CX["Codex JSONL"]
+      CU["Cursor SQLite"]
+    end
+
+    CC --> I["incremental indexer"]
+    CX --> I
+    CU -->|"consistent WAL snapshot"| I
+    I --> V["conversation surface → embeddings"]
+    I --> R["raw trace, kept local"]
+    V --> DB["SQLite · sqlite-vec KNN · FTS5"]
+    R --> DB
+    DB --> MCP["five on-demand MCP tools"]
+    MCP --> A["Claude Code · Codex · Cursor · any MCP client"]
 ```
 
-Freshness compares the newest transcript on disk against the newest turn in the index,
-so an indexer that runs on every session and fails every time still shows as behind —
-which is exactly the failure that is otherwise invisible.
+Only the conversation "surface" is embedded — user prompts and assistant text replies. Tool
+calls, results, reasoning, and other trace data are never sent to an embedding provider but
+stay reachable on demand via `expand_around`, `step`, and `grep`. Claude sidechains and
+spawned-subagent sessions are intentionally skipped: under-the-hood tooling, not the
+conversation.
 
-| Symptom | Cause |
-|---|---|
-| `recall_search` answers with `degraded` set | The embedding provider is unreachable — only literal word matching ran. Results are still real, but a miss proves nothing. |
-| `degraded` says "embedder changed" | The index was built in a different embedding space than the current config. Run `session-recall index` to re-embed; semantic ranking stays off until then, on purpose. |
-| Indexer logs `HTTP code 403` with an HTML body | Not your key: a WAF is blocking your IP (common on VPN and datacenter exits). Same 403 appears with no key at all. Route egress elsewhere or switch provider. |
-| `Missing dependencies for SOCKS support` | A SOCKS proxy is set in the environment but `PySocks` is not installed in that venv. |
-| `recent_sessions` shows an old timestamp | The indexer has not succeeded recently. Run `session-recall index` by hand and read the output. |
+Cursor is read from its SQLite store with the online backup API, so a live WAL database is
+captured consistently without blocking the editor. Its bubbles are normalized into durable,
+content-addressed JSONL snapshots under the data directory — deep navigation keeps working
+after Cursor closes, upgrades, or is uninstalled.
 
-### CLI reference
+Indexing is incremental and cheap on live transcripts: they are append-only, so unchanged
+chunks are matched by content hash and their vectors reused — only new turns hit the
+embedding provider. Moving a Codex rollout into the archive also reuses its vectors. Each
+file indexes in its own transaction; a failing file is logged and retried next run, never
+aborting the rest.
+
+## CLI cheat sheet
 
 ```bash
-session-recall index --source claude|codex|cursor|all   # defaults to all
-session-recall search "query" --source codex
-session-recall recent --date 2026-07-14          # this computer's timezone
-session-recall search "deployment work" --start-date 2026-07-14 \
-  --end-date 2026-07-14 --timezone Asia/Yekaterinburg
-session-recall grep "exact" --limit 100          # raw scan, no API key needed
-session-recall prune                             # drop rows for deleted transcripts
-```
+# Refresh every history, or one source
+session-recall index
+session-recall index --source cursor
 
-`search`, `recent`, `grep`, and `prune` all take an optional `--source claude|codex|cursor`; omit it to
-search the unified history. Date filters are inclusive and either boundary may be omitted; the timezone
-defaults to this computer's and accepts any IANA name. `grep` caps at 100 matches by default.
+# Semantic search — unified by default, scopable to a repo
+session-recall search "why did we choose the keeper service?"
+session-recall search "deployment work" --source codex --scope /work/keeper
 
-For development, an in-tree virtualenv works too:
+# Local calendar dates, any IANA timezone (defaults to this computer's)
+session-recall recent --date 2026-07-14
+session-recall search "deployment work" \
+  --start-date 2026-07-14 --end-date 2026-07-16 \
+  --timezone Asia/Yekaterinburg
 
-```bash
-python -m venv .venv && .venv/bin/pip install -e .
-.venv/bin/session-recall index
-```
-
-To register the MCP server by hand instead of using the plugin:
+# Exact raw scan — no embedding call, caps at 100 matches by default
+session-recall grep "invalid_grant" --limit 100
 
-```bash
-claude mcp add session-recall --scope user -- /absolute/path/.venv/bin/session-recall-mcp
+# Housekeeping
+session-recall prune    # drop rows for transcripts deleted from disk
+session-recall health   # the whole chain, verdict GREEN/AMBER/RED
 ```
 
+`search`, `recent`, `grep`, and `prune` all take `--source claude|codex|cursor`; omit it for
+the unified history. Date filters are inclusive and either boundary may be omitted.
+
 ## Embedding providers
 
 Nothing is locked to one vendor. `SESSION_RECALL_EMBED=<preset>` sets endpoint, model,
-dimension and reranker together, because those four are not independent choices:
+dimension, and reranker together, because those four are not independent choices:
 
-| preset | runs | model | dim | reranker |
-|---|---|---|---|---|
-| `voyage` | hosted, needs a key | `voyage-4-large` | 1024 | `rerank-2.5` |
-| `ollama` | **local, free** | `nomic-embed-text` | 768 | — |
-| `lmstudio` | **local, free** | `nomic-embed-text-v1.5` | 768 | — |
-| `openai` | hosted, needs a key | `text-embedding-3-large` | 1024 | — |
+| Preset | Runs | Model | Dim | Reranker |
+|---|---|---|---:|---|
 | `builtin-en` | **bundled, free** | `bge-small-en-v1.5` | 384 | — |
 | `builtin-zh` | **bundled, free** | `bge-small-zh-v1.5` | 512 | — |
 | `builtin-multi` | **bundled, free** | `paraphrase-multilingual-MiniLM-L12-v2` | 384 | — |
+| `ollama` | **local, free** | `nomic-embed-text` | 768 | — |
+| `lmstudio` | **local, free** | `nomic-embed-text-v1.5` | 768 | — |
+| `voyage` | hosted, needs a key | `voyage-4-large` | 1024 | `rerank-2.5` |
+| `openai` | hosted, needs a key | `text-embedding-3-large` | 1024 | — |
 
-With no preset set, session-recall picks Voyage when `VOYAGE_API_KEY` is
-present, then probes for a local server already listening, and otherwise runs
-the **bundled ONNX model** — out of the box always works. The bundled flavor
-follows the interaction language you choose at onboarding
-(`SESSION_RECALL_LANG=en|zh|…`; a small English or Chinese specialist,
-multilingual for every other answer and for no answer at all — `builtin` as a
-preset name resolves the same way). First use downloads the model once into
-the data dir (70–240MB), CPU inference from then on; ranking is noticeably
-coarser than hosted Voyage — a starting point, not the ceiling. With a key
-configured, no probe runs.
+With no preset set, Session Recall picks Voyage when `VOYAGE_API_KEY` is present, then
+probes for a local server already listening, and otherwise runs the bundled ONNX model —
+out of the box always works. The bundled flavor follows the interaction language you chose
+at onboarding (`SESSION_RECALL_LANG=en|zh|…`: a small English or Chinese specialist,
+multilingual otherwise). First use downloads the model once into the data dir (70–240 MB),
+CPU inference from then on. Ranking is noticeably coarser than hosted Voyage — a starting
+point, not the ceiling. Local presets ship no reranker, so ranking is KNN + FTS only.
 
 **Free and local, start to finish:**
 
@@ -282,8 +304,8 @@ export SESSION_RECALL_EMBED=ollama
 session-recall index
 ```
 
-**Your own endpoint** — any server speaking `/v1/embeddings` (llama.cpp, vLLM, a
-company gateway). Individual variables always beat the preset, so mix freely:
+**Your own endpoint** — any server speaking `/v1/embeddings` (llama.cpp, vLLM, a company
+gateway). Individual variables always beat the preset, so mix freely:
 
 ```bash
 export SESSION_RECALL_EMBED_PROVIDER=openai-compatible
@@ -292,32 +314,34 @@ export SESSION_RECALL_EMBED_MODEL=your-model
 export SESSION_RECALL_EMBED_DIM=1024
 ```
 
-Two things worth knowing before you switch:
+**A different embedder needs its own index.** Vector tables are fixed-width, so changing
+the model or dimension means rebuilding: delete `~/.local/share/session-recall/index.db`
+and re-run `index`. Session Recall fingerprints the embedding space of every indexed file
+and refuses to mix spaces — semantic search shuts off with an explicit message instead of
+returning misleading rankings.
 
-- **A different embedder needs its own index.** Vector tables are fixed-width, so
-  changing the model or dimension means rebuilding: delete
-  `~/.local/share/session-recall/index.db` and re-run `index`. Attempting to reuse the old
-  one now fails with a message saying exactly that, rather than looking like a dead
-  embedder.
-- **Local presets ship no reranker**, so ranking is KNN + FTS only — good enough, but
-  noticeably coarser than the hosted path.
+<details>
+<summary><strong>Model licensing notes</strong></summary>
 
-On model choice: `nomic-embed-text` is the default because it is Apache-2.0 and installs in
-one command. Stronger small models exist — `jina-embeddings-v5-text-nano` scores far higher
-for its size — but they are **CC BY-NC**, which anyone indexing work history would be
-violating without ever being told. If your use is genuinely non-commercial, point the
-variables above at one. If you work in more than English, `qwen3-embedding:0.6b` (Apache-2.0)
-handles multilingual history far better than `nomic`.
+`nomic-embed-text` is the local default because it is Apache-2.0 and installs in one
+command. Stronger small models exist — `jina-embeddings-v5-text-nano` scores far higher for
+its size — but they are **CC BY-NC**, which anyone indexing work history would be violating
+without ever being told. If your use is genuinely non-commercial, point the variables above
+at one. If you work in more than English, `qwen3-embedding:0.6b` (Apache-2.0) handles
+multilingual history far better than `nomic`.
+
+</details>
 
 ## Keeping the index fresh
 
-If you installed the plugin, this is already handled — skip to the next section. The bundled
-`SessionStart` hook works on both hosts and runs `session-recall index` in the background, and
-the default `--source all` refreshes all three histories. Indexing is incremental (it skips
-already-indexed files by signature), so staying fresh is cheap.
+If you installed a plugin, this is already handled: the bundled `SessionStart` hook runs
+`session-recall index` in the background on every session start, and incremental indexing
+keeps it cheap.
+
+<details>
+<summary><strong>Registered the MCP server by hand? Add the hook yourself</strong></summary>
 
-Only if you registered the MCP server by hand, add the hook yourself in
-`~/.claude/settings.json`:
+In `~/.claude/settings.json`:
 
 ```json
 "hooks": {
@@ -331,105 +355,87 @@ Only if you registered the MCP server by hand, add the hook yourself in
 ```
 
 The `pgrep` guard prevents overlapping runs; `( … & )` detaches so session start doesn't
-wait. Keep the host-level hook synchronous: the shell already backgrounds the indexer, and
-Codex ignores Claude's `async` extension. A `launchd`/cron timer is another option. (Local on one machine is enough; a server-side
-index only makes sense across several machines — at the cost of privacy and network.)
+wait. Keep the host-level hook synchronous — the shell already backgrounds the indexer, and
+Codex ignores Claude's `async` extension. A `launchd`/cron timer works too.
+
+</details>
 
 ## Team mode — ask a colleague's history
 
-The same recall, across machines: pair with a colleague once, and your agent can ask
-their agent about their past work.
+The same recall, across machines: pair with a colleague once, and your agent can ask their
+agent about their past work.
 
-> **you → a colleague's agent:** when you hit the local-launch problem with X — how did
-> you solve it?
+> **you → a colleague's agent:** when you hit the local-launch problem with X — how did you
+> solve it?
 >
-> **their agent** *(after the colleague approves the answer)*: pin the config to …, then
-> …, and the problem does not come back.
+> **their agent** *(after the colleague approves the answer)*: pin the config to …, then …,
+> and the problem does not come back.
 
-The agents negotiate the details between themselves; what used to be a Slack thread and a
-half-remembered explanation becomes one question and one grounded answer. You never see
-the colleague's raw history — only the approved answer.
+What used to be a Slack thread and a half-remembered explanation becomes one question and
+one grounded answer. You never see the colleague's raw history — only the answer they
+approved.
 
 Privacy here is mechanics, not policy:
 
-- questions and answers travel as **end-to-end encrypted envelopes** through a relay that
-  stores blind blobs — the relay cannot read them;
-- answers are built by an **isolated read-only worker**, scoped to the projects that
-  contact was explicitly granted (`share allow`);
-- every candidate answer passes a **secret scanner** and then **explicit approval** by
-  the owner (Telegram bot, or `share approve` locally) before it leaves the machine;
+- questions and answers travel as **end-to-end encrypted envelopes**; the relay stores blind
+  blobs it cannot read;
+- answers are built by an **isolated read-only worker**, scoped to the projects that contact
+  was explicitly granted (`share allow`);
+- every candidate answer passes a **secret scanner** and then **explicit owner approval**
+  (Telegram bot, or `share approve` locally) before it leaves the machine;
 - a contact can be paused any time (`share pause`), a peer revoked (`share revoke`).
 
-### Pick a transport (once, before pairing)
+Searching a peer's index needs no embedding setup on your side: the query travels as text,
+and the owner's worker embeds it with their own provider against their own index.
+
+<details>
+<summary><strong>Pick a transport (once, before pairing)</strong></summary>
 
-Nothing is baked in: a fresh install has **no transport** and never talks to a
-server you didn't choose. The relay is blind — everything it carries is sealed
-and signed on the clients — so which one to use is coordination between peers,
-not a matter of trust. Three recipes, simplest first:
+A fresh install has **no transport** and never talks to a server you didn't choose. The
+relay is blind — everything it carries is sealed and signed on the clients — so which one to
+use is coordination between peers, not a matter of trust.
 
-**Shared folder — zero infrastructure.** Two accounts on one machine, or any
-folder both peers sync (Syncthing, Dropbox, an NFS mount):
+**Shared folder — zero infrastructure.** Two accounts on one machine, or any folder both
+peers sync (Syncthing, Dropbox, an NFS mount):
 
 ```bash
 export SESSION_RECALL_SHARE_TRANSPORT_DIR=~/Sync/sr-share   # both peers, same folder
 ```
 
-**Your relay on the LAN.** One machine runs it, everyone points at it.
-Envelopes are end-to-end encrypted regardless, but this is plain HTTP —
-mailbox addresses travel readable, so keep it to a network you trust:
+**Your relay on the LAN.** One machine runs it, everyone points at it. Envelopes are
+end-to-end encrypted regardless, but this is plain HTTP — keep it to a network you trust:
 
 ```bash
 session-recall share relay --port 8787 --host 0.0.0.0       # on the relay machine
 export SESSION_RECALL_RELAY_URL=http://192.168.1.20:8787    # on every peer
 ```
 
-**Your relay on the internet.** The relay binds localhost on purpose and
-expects a TLS terminator in front. On the server:
+**Your relay on the internet.** The relay binds localhost on purpose and expects a TLS
+terminator in front (Caddy is the two-line option):
 
 ```bash
-pipx install git+https://github.com/AbsoluteMode/session-recall
 session-recall share relay --port 8787    # binds 127.0.0.1
 ```
 
-As a user systemd service (`~/.config/systemd/user/sr-relay.service`):
-
-```ini
-[Unit]
-Description=session-recall share relay
-
-[Service]
-ExecStart=%h/.local/bin/session-recall share relay --port 8787
-Restart=on-failure
-
-[Install]
-WantedBy=default.target
-```
-
-```bash
-systemctl --user enable --now sr-relay
-loginctl enable-linger $USER              # keep it alive after logout
-```
-
-Any TLS proxy in front works; Caddy is the two-line option:
-
-```
+```text
 relay.example.com {
     reverse_proxy 127.0.0.1:8787
 }
 ```
 
-Then on every peer: `export SESSION_RECALL_RELAY_URL=https://relay.example.com`.
-The relay stores only sealed blobs under `<data-dir>/share-relay`, and a
-mailbox is emptied on fetch; `SESSION_RECALL_RELAY_URL=none` keeps an install
-network-silent on purpose. Put the `export` in your shell profile so agents
+Then on every peer: `export SESSION_RECALL_RELAY_URL=https://relay.example.com`. The relay
+stores only sealed blobs, and a mailbox is emptied on fetch. `SESSION_RECALL_RELAY_URL=none`
+keeps an install network-silent on purpose. Put the `export` in your shell profile so agents
 and timers see it too.
 
-### Pairing
+</details>
+
+<details>
+<summary><strong>Pairing and asking</strong></summary>
 
 Pairing is a one-time ceremony with a short SAS check, then asking is one command:
 
 ```bash
-export SESSION_RECALL_RELAY_URL=https://relay.example.com   # both sides: the transport you picked
 session-recall share init            # once per device, both sides
 session-recall share invite          # you: prints a one-time code
 session-recall share join <code>     # colleague: accepts it
@@ -442,27 +448,23 @@ session-recall share ask <name> "how did you fix the local X launch?"
 session-recall share fetch           # collect the answers
 ```
 
-Searching a peer's index needs no embedding setup on your side: the query travels as
-text, and the owner's worker embeds it with their own provider against their own index.
-
-## meta docs — the project's memory, written down
+</details>
 
-Raw recall answers "what was said". meta docs answers the questions agents
-actually ask mid-task: *was this bug fixed before? how do I perform this
-action? why was it decided this way?* A daily job hands each session's
-dialogue — user messages and final answers only, never the tool noise — to a
-distiller agent that maintains entries in a git repository of your choice:
+## Meta docs — the project's memory, written down
 
-- `<project>/bugs/` — bugs that were actually fixed: how each was recognized,
-  diagnosed, fixed, and proven fixed;
-- `<project>/actions/` — procedures, step by step, written so an agent asked
-  again can follow the entry alone;
-- `<project>/decisions/` — contested choices: what was decided, why that way,
-  what was rejected;
-- `USER/` — a global map of where your information lives and *how to find it*
-  (lookup commands, storage locations — never the stored values themselves).
+Raw recall answers *what was said*. Meta docs answers what agents actually ask mid-task:
+*was this bug fixed before? how do I perform this action? why was it decided this way?* A
+daily job hands each session's dialogue — user messages and final answers, never the tool
+noise — to a distiller agent that maintains Markdown entries in a Git repository you choose:
 
-One file per entry, with related PRs and source sessions in the frontmatter.
+- `<project>/bugs/` — bugs that were actually fixed: how each was recognized, diagnosed,
+  fixed, and proven fixed;
+- `<project>/actions/` — procedures, step by step, written so an agent asked again can
+  follow the entry alone;
+- `<project>/decisions/` — contested choices: what was decided, why that way, what was
+  rejected;
+- `USER/` — a global map of where your information lives and *how to find it* (lookup
+  commands and storage locations — never the stored values themselves).
 
 ```bash
 session-recall metadocs init ~/meta-docs --from-today   # memory starts now
@@ -472,45 +474,106 @@ session-recall metadocs status
 session-recall metadocs index-history --days 30         # opt-in: distill the past, once
 ```
 
-The agent's whole world is four MCP verbs — `search / create / edit /
-delete` — and the load-bearing rules are server mechanics, not prompt
-requests: `create` is refused until the agent has `search`ed (dedup is
-mandatory), entries are scanned for secrets before a byte reaches disk, and
-`delete` demands a reason. Every built-in tool is stripped from the call.
-Runs are incremental (per-session watermarks) and each changed project gets
-its own commit — review is a diff, undo is a revert, and sharing the memory
-with a team is just pushing the repo somewhere private. Commits stay local
-unless you opt into `--push`; the distilling agent and model come from config only
-(`init --engine claude-cli|codex --model … [--reasoning …]`) — nothing is picked
-silently. The daily job never touches history; `index-history` is the only door to
-the past.
+The distiller's whole world is four MCP verbs — `search / create / edit / delete` — and the
+load-bearing rules are server mechanics, not prompt requests: `create` is refused until the
+agent has `search`ed (dedup is mandatory), entries are scanned for secrets before a byte
+reaches disk, and `delete` demands a reason. Runs are incremental, and each changed project
+gets its own local commit — review is a diff, undo is a revert, and sharing the memory with
+a team is just pushing the repo somewhere private. Nothing is pushed unless you opt into
+`--push`; the engine and model come from config only
+(`init --engine claude-cli|codex --model …`) — nothing is picked silently.
+
+## Privacy is a hard invariant
+
+This is a public repository. **Only code goes in it.** Runtime data lives under
+`~/.local/share/session-recall/`, outside the repo tree — it physically cannot be committed.
+
+| Stays on your machine | Leaves only when you choose it |
+|---|---|
+| Original Claude Code and Codex transcripts | Conversation surface text → your configured hosted embedder |
+| Cursor's SQLite store and its normalized snapshots | An explicitly approved team-mode answer |
+| Tool calls, outputs, reasoning — the whole raw trace | Nothing, on the bundled/local embedding path |
+| The SQLite index and stored vectors | |
+
+- API keys are environment variables only; `.gitignore` blocks `.env`.
+- Tests use synthetic fixtures, never a real slice of a session.
+- The bundled provider keeps the entire indexing path on-device. If you choose a hosted
+  provider, pick one you trust with your transcript surface text.
+
+## Troubleshooting
+
+Start here — it checks the whole chain and exits non-zero when something is actually
+broken, so it also works from a timer:
+
+```console
+$ session-recall health
+[ok  ] Freshness  2 minutes behind
+[warn] Embedder   responded in 5828 ms
+                  → slow provider will make indexing crawl
+[ok  ] Vector space  builtin/BAAI/bge-small-en-v1.5/384
+[ok  ] Corpus     1054 sessions (claude 373, codex 680, cursor 1)
+[ok  ] Sources    claude, codex, cursor present
+
+verdict: AMBER (voyage/voyage-4-large, index at ~/.local/share/session-recall/index.db)
+```
+
+Freshness compares the newest transcript on disk against the newest turn in the index, so
+an indexer that runs on every session and fails every time still shows as behind — exactly
+the failure that is otherwise invisible.
+
+| Symptom | Cause / next step |
+|---|---|
+| `recall_search` answers with `degraded` set | The embedding provider is unreachable — only literal matching ran. Results are real, but a miss proves nothing. |
+| `degraded` says "embedder changed" | The index was built in a different embedding space. Run `session-recall index` to re-embed; semantic ranking stays off until then, on purpose. |
+| Indexer logs `HTTP code 403` with an HTML body | Not your key: a WAF is blocking your IP (common on VPN and datacenter exits). The same 403 appears with no key at all. Route egress elsewhere or switch provider. |
+| `Missing dependencies for SOCKS support` | A SOCKS proxy is set in the environment but `PySocks` is not installed in that venv. |
+| `recent_sessions` shows an old timestamp | The indexer has not succeeded recently. Run `session-recall index` by hand and read the output. |
+| Cursor lives in a custom profile | Set `SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`. |
+
+## Development
+
+```bash
+git clone https://github.com/AbsoluteMode/session-recall.git
+cd session-recall
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest -q
+```
+
+To register the MCP server by hand instead of using the plugin:
+
+```bash
+claude mcp add session-recall --scope user -- /absolute/path/.venv/bin/session-recall-mcp
+```
+
+Engineering rationale and invariants live in [`docs/decisions/`](docs/decisions/). Start with:
+
+- [Unified Claude Code + Codex index](docs/decisions/2026-07-10-unified-claude-codex-index.md)
+- [Cursor as a durable raw source](docs/decisions/2026-08-03-cursor-durable-raw-source.md)
+- [Project-scoped recall](docs/decisions/2026-06-26-recall-project-scope.md)
+- [P2P sharing security gate](docs/decisions/2026-07-30-p2p-sharing-v1-security-gate.md)
+- [Meta docs living project memory](docs/decisions/2026-07-31-metadocs-living-project-memory.md)
 
 ## Roadmap
 
 - **Hosted/team index** — one shared index for a team instead of per-machine copies. The
   honest open question: whoever searches must embed the query, so a shared vector space
-  implies a shared embedding path (a team key, or a small embedding proxy in front of
-  the provider).
-- **Per-contact bypass** — skip per-answer approval for peers you fully trust; today
-  every answer is approved explicitly.
-- **More histories** — Cursor shipped as the third source (sessions are read
-  from its SQLite store, subagents skipped, workspace mapped to a project);
-  other agents' transcripts next.
-
-## Privacy — hard invariant
-
-This is a public repository. **Only code goes in it.**
-
-- Data, indexes, raw transcripts, embeddings → `~/.local/share/session-recall/`,
-  **outside the repo tree**. They physically cannot be committed.
-- API keys → environment only (`VOYAGE_API_KEY`); `.gitignore` blocks `.env`.
-- Tests → synthetic fixtures only, never a real slice of a session.
-- Claude Code transcripts, active and archived Codex transcripts, and Cursor's
-  SQLite store are read locally. Cursor's normalized raw snapshots stay under
-  the data directory. Only user/assistant surface text is embedded;
-  tool/reasoning trace data stays out of embeddings and is exposed only by
-  explicit raw expansion or grep.
-- Chunk texts ARE sent to your configured embedding/rerank provider. With no
-  key or local server the bundled provider stays entirely on-device; if you
-  choose Voyage or another hosted endpoint, pick one you trust with your
-  transcript surface text.
+  implies a shared embedding path.
+- **Per-contact approval bypass** — skip per-answer approval for peers you fully trust;
+  today every answer is approved explicitly.
+- **More histories** — other agents' transcripts beyond Claude Code, Codex, and Cursor.
+
+## Contributing
+
+Issues, documentation improvements, host adapters, and translations are welcome. Keep
+fixtures synthetic and never commit real transcripts, indexes, embeddings, or credentials.
+
+<div align="center">
+  <br />
+  <strong>Stop rebuilding context. Continue it.</strong>
+  <br />
+  <br />
+  <a href="#quick-start">Get started</a>
+  &nbsp;·&nbsp;
+  <a href="LICENSE">MIT License</a>
+</div>
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..de343cc
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,556 @@
+<div align="center">
+
+<a href="#快速开始">
+  <img src="assets/og.webp" alt="Session Recall——你的编码智能体会遗忘，Session Recall 不会。Claude Code、Codex 与 Cursor 共用的一份记忆。" width="100%" />
+</a>
+
+<br />
+<br />
+
+<strong>Claude Code、Codex 与 Cursor 的共享语义记忆。</strong><br />
+按语义找回旧日决策。打开原始证据。继续当时的工作。
+
+<br />
+<br />
+
+[![MIT License](https://img.shields.io/badge/license-MIT-b8f84f?style=flat-square&labelColor=11120f)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-b8f84f?style=flat-square&labelColor=11120f)](pyproject.toml)
+[![MCP native](https://img.shields.io/badge/MCP-native-b8f84f?style=flat-square&labelColor=11120f)](src/session_recall/server.py)
+[![Tests](https://img.shields.io/github/actions/workflow/status/AbsoluteMode/session-recall/test.yml?branch=main&style=flat-square&label=tests&labelColor=11120f)](https://github.com/AbsoluteMode/session-recall/actions/workflows/test.yml)
+
+<br />
+
+[English](README.md) · [Русский](docs/README.ru.md) · [Español](README.es-ES.md) · 中文
+
+*英文版为基准版本，翻译可能滞后。*
+
+</div>
+
+---
+
+你的编码智能体只记得当前这场对话，而你的工作散落在数月的对话之中——
+被恢复的会话、并行的订阅、多个 worktree、不同的智能体。
+
+Session Recall 把这些历史汇成一个本地优先的索引，再通过五个专注的 MCP 工具提供出来。
+新会话可以找回 Codex 昨天想通的方案、Claude Code 三个月前否掉的思路——并附上指回
+真实对话轮次、工具输出与推理过程的链接。它不是谁手工维护的摘要文件：
+原始对话始终是事实来源。
+
+> **你：** 我们之前在修两个服务之间的认证令牌冲突——最后是怎么定的？
+>
+> **智能体：** *(recall_search → expand_around)* 两个服务共用同一个 OAuth 账号，而提供方按
+> 账号轮换刷新令牌，因此任何一方刷新都会让另一方的副本失效。你否掉了共享凭据目录的补丁，
+> 认为耦合太重，最终定下由一个 keeper 服务独占该会话。规格说明一直没写——那正是下一步。
+
+## 你会得到什么
+
+| | 能力 | 带来的改变 |
+|---|---|---|
+| **同一份记忆** | Claude Code、Codex 和 Cursor 写入同一个索引 | 切换智能体时无需从头重述项目脉络 |
+| **语义检索** | 按语义搜索，而不只是精确字词 | 找回那些你能描述却无法逐字引用的决策 |
+| **深度导航** | 打开原始轮次：工具调用、输出、推理过程 | 亲自核实答案，而不是轻信摘要 |
+| **诚实降级** | 语义搜索失效时会被明确报告 | 纯字面回退绝不冒充语义搜索 |
+| **默认本地** | 内置 ONNX 嵌入与本地 SQLite | 无需密钥、服务器或账号即可上手 |
+| **按范围召回** | 按仓库、来源或本地日历日期过滤 | 把无关项目挡在答案之外 |
+| **团队问答** | 询问同事的本地记忆，经所有者批准 | 分享来之不易的上下文，而不暴露原始会话 |
+
+## 在哪些场景见效
+
+- **会话入场。** 新会话一开始就带着上下文——无论你同时打理几份订阅、在智能体之间
+  来回切换，还是回到某个“当时聊过”的任务。
+- **Bug 与回归。** 动手修复之前，智能体先向历史提问：*这个 bug 以前见过吗？当时怎么修的？
+  我们凭什么相信它修好了？* 复发不再像一个全新的 bug——修复也从打补丁变成对组件的深挖。
+- **操作流程。** 一套流程只讲一遍——怎么读一份 trace、怎么按任务拆解 token 开销——
+  之后的任何会话都能照着重演，无需再被手把手带一遍。
+- **因果关系。** 当你说“我们改掉这个决定吧”，智能体会找出当初拍板的那一刻：
+  *“选 X 是为了兼容 Y——动手之前，先确认 Y 不受影响。”*
+
+## 五个工具，一条工作流
+
+接口刻意保持精简：
+
+| MCP 工具 | 何时使用 |
+|---|---|
+| `recall_search(query)` | 你记得大意，却记不清原话 |
+| `expand_around(session_id, uuid)` | 你已找到锚点，需要它周围的证据 |
+| `step(session_id, uuid, direction)` | 你想看相邻的原始轮次，而不想再搜一遍 |
+| `grep(pattern)` | 你手里有精确的报错、符号、路径或标识符 |
+| `recent_sessions()` | 你想要最新的工作——以及索引的新鲜度 |
+
+```mermaid
+flowchart LR
+    Q["describe the old problem"] --> S["recall_search"]
+    S --> A["ranked anchor"]
+    A --> E["expand_around"]
+    E --> T["step next / prev"]
+    Q -. exact identifier .-> G["grep"]
+    R["what is current?"] --> RS["recent_sessions"]
+```
+
+每个检索工具都接受可选的 `source`（`claude` | `codex` | `cursor`）、把结果收窄到当前仓库的
+`scope_cwd`（worktree 会折叠到仓库根目录），以及本地日历日期（`on_date`，或
+`start_date` / `end_date`，外加 IANA `timezone`）。排好序的锚点自带出处与人类可读的时间戳。
+`grep` 按需扫描**所有**已索引的会话记录——包括那些从未成为搜索分块的幕后轮次
+（工具输出、思考过程）。一切只按需进行：不会向每条提示词主动注入上下文。
+
+<details>
+<summary><strong>查看一次完整调用</strong></summary>
+
+```json
+{
+  "query": "why did refresh tokens conflict?",
+  "scope_cwd": "/work/keeper",
+  "source": "codex",
+  "start_date": "2026-05-01",
+  "end_date": "2026-06-30",
+  "timezone": "Europe/Moscow"
+}
+```
+
+`recall_search` 的应答形如 `{"anchors": [...], "degraded": null | "reason"}`。当 `degraded`
+被置位时，说明嵌入提供方不可达、只运行了字面匹配——智能体可以如实说明这一点，
+而不是把一次词面未命中误当作历史为空。
+
+</details>
+
+## 快速开始
+
+一共两件东西：一个 Python CLI（同时附带 MCP 服务器），以及把它接进智能体的插件。
+预留大约两分钟，外加首次索引运行的时间。
+
+### 1. 安装 CLI 并构建索引
+
+```bash
+pipx install git+https://github.com/AbsoluteMode/session-recall
+session-recall setup   # one question (interaction language), then the first index
+```
+
+无需密钥：在什么都不配置的情况下，索引由内置的 CPU 模型完成，模型只下载一次，
+并按你的交互语言选定。首次运行会走完你的全部历史——数月的会话记录需要几分钟，
+之后每次只要几秒。脚本化安装：`session-recall setup --lang en --yes`。
+
+```console
+$ session-recall index
+indexed 2175 chunks from changed transcripts
+
+your history: 1053 sessions spanning 168 days, 40,037 searchable fragments
+  Claude Code 372 · Codex 680 · Cursor 1
+  busiest: sidekey, trend_detection, glitch
+```
+
+托管的 Voyage 嵌入在排序上明显优于内置模型；要使用它，请在索引前导出
+`VOYAGE_API_KEY`——参见[嵌入提供方](#嵌入提供方)。
+
+### 2. 接入你的智能体
+
+`pipx` 会把 `session-recall` 和 `session-recall-mcp` 放到 `~/.local/bin`——插件清单
+正是在那里查找它们。
+
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+```text
+/plugin marketplace add AbsoluteMode/session-recall
+/plugin install session-recall
+```
+
+然后开启一个新会话——MCP 服务器、技能和 SessionStart 钩子在会话启动时加载，
+而不是安装时。想让智能体替你把事办完？对它说 `set up session-recall`
+（或运行 `/session-recall:setup`）：它会在对话中问完引导问题、自己执行命令，
+最后以一次健康检查和一次针对你真实历史的搜索收尾。
+
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+仓库自带原生的 [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json)——可直接放进
+本地仓库或你的个人 marketplace；参见
+[本地插件安装指南](https://learn.chatgpt.com/docs/build-plugins#install-a-local-plugin-manually)。
+Codex 还会要求你通过 `/hooks` 对新安装的钩子审查一次。
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+需要 Cursor 2.5+（插件正是在该版本引入的）。把本仓库添加为 marketplace：
+
+```bash
+cursor-agent plugin marketplace add https://github.com/AbsoluteMode/session-recall.git
+```
+
+然后在 Cursor Agent 里输入 `/add-plugin session-recall`，并对本地 stdio MCP 服务器
+批准一次，工具即可启动。若要做插件开发，请用
+`cursor-agent --plugin-dir /absolute/path/to/session-recall` 启动，而不是安装缓存副本。
+
+Cursor 会按其 macOS/Linux 常规数据路径被自动检测，且无需处于运行状态。
+便携版或自定义配置目录？用
+`SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb` 直接指向数据库。
+
+</details>
+
+### 3. 验证是否生效
+
+```bash
+session-recall search "something you actually discussed last week"
+```
+
+结果带有 `score` 就说明语义搜索已生效。在智能体里，`claude mcp list` 应显示
+`session-recall ✔ Connected`，而询问过去的工作应触发 `recall_search`。再无其他要配置的：
+每个插件都自带其宿主的启动钩子并在后台重新索引，共享索引会自行跟上三份历史的进度。
+
+## 工作原理
+
+```mermaid
+flowchart TB
+    subgraph Sources["local history sources"]
+      CC["Claude Code JSONL"]
+      CX["Codex JSONL"]
+      CU["Cursor SQLite"]
+    end
+
+    CC --> I["incremental indexer"]
+    CX --> I
+    CU -->|"consistent WAL snapshot"| I
+    I --> V["conversation surface → embeddings"]
+    I --> R["raw trace, kept local"]
+    V --> DB["SQLite · sqlite-vec KNN · FTS5"]
+    R --> DB
+    DB --> MCP["five on-demand MCP tools"]
+    MCP --> A["Claude Code · Codex · Cursor · any MCP client"]
+```
+
+只有对话的“表层”会被嵌入——用户提示词与助手的文字回复。工具调用、结果、推理过程
+及其他追踪数据绝不会发送给嵌入提供方，但始终可以通过 `expand_around`、`step` 和 `grep`
+按需取到。Claude 的 sidechain 与派生子智能体的会话被有意跳过：那是幕后的工具活动，
+不是对话。
+
+Cursor 的数据经 online backup API 从其 SQLite 存储读取，因此活动中的 WAL 数据库也能
+被一致地捕获，且不阻塞编辑器。其 bubble 会被规范化为数据目录下持久、按内容寻址的
+JSONL 快照——即使 Cursor 关闭、升级或被卸载，深度导航依然可用。
+
+索引是增量式的，对活跃会话记录开销很小：它们只会追加，未变化的分块按内容哈希匹配
+并复用已有向量——只有新轮次才会触达嵌入提供方。把 Codex rollout 移入归档同样复用
+其向量。每个文件在自己的事务中完成索引；失败的文件会被记录并在下次运行时重试，
+绝不拖垮其余文件。
+
+## CLI 速查表
+
+```bash
+# Refresh every history, or one source
+session-recall index
+session-recall index --source cursor
+
+# Semantic search — unified by default, scopable to a repo
+session-recall search "why did we choose the keeper service?"
+session-recall search "deployment work" --source codex --scope /work/keeper
+
+# Local calendar dates, any IANA timezone (defaults to this computer's)
+session-recall recent --date 2026-07-14
+session-recall search "deployment work" \
+  --start-date 2026-07-14 --end-date 2026-07-16 \
+  --timezone Asia/Yekaterinburg
+
+# Exact raw scan — no embedding call, caps at 100 matches by default
+session-recall grep "invalid_grant" --limit 100
+
+# Housekeeping
+session-recall prune    # drop rows for transcripts deleted from disk
+session-recall health   # the whole chain, verdict GREEN/AMBER/RED
+```
+
+`search`、`recent`、`grep` 和 `prune` 都接受 `--source claude|codex|cursor`；省略即为
+统一历史。日期过滤是闭区间，两端边界均可省略。
+
+## 嵌入提供方
+
+不锁定任何单一供应商。`SESSION_RECALL_EMBED=<preset>` 会把端点、模型、维度和重排序器
+一并设定，因为这四项并不是相互独立的选择：
+
+| 预设 | 运行方式 | 模型 | 维度 | 重排序器 |
+|---|---|---|---:|---|
+| `builtin-en` | **内置，免费** | `bge-small-en-v1.5` | 384 | — |
+| `builtin-zh` | **内置，免费** | `bge-small-zh-v1.5` | 512 | — |
+| `builtin-multi` | **内置，免费** | `paraphrase-multilingual-MiniLM-L12-v2` | 384 | — |
+| `ollama` | **本地，免费** | `nomic-embed-text` | 768 | — |
+| `lmstudio` | **本地，免费** | `nomic-embed-text-v1.5` | 768 | — |
+| `voyage` | 托管，需要密钥 | `voyage-4-large` | 1024 | `rerank-2.5` |
+| `openai` | 托管，需要密钥 | `text-embedding-3-large` | 1024 | — |
+
+未设置预设时，Session Recall 的取舍顺序是：存在 `VOYAGE_API_KEY` 时选 Voyage，
+其次探测已在监听的本地服务器，否则运行内置 ONNX 模型——开箱即用永远成立。
+内置模型的具体选型跟随你在引导时选定的交互语言（`SESSION_RECALL_LANG=en|zh|…`：
+英文或中文各有小型专用模型，其余语言用多语言模型）。首次使用会把模型一次性下载到
+数据目录（70–240 MB），此后始终在 CPU 上推理。其排序明显粗于托管的 Voyage——
+是起点，不是上限。本地预设不带重排序器，因此排序只靠 KNN + FTS。
+
+**从头到尾免费且本地：**
+
+```bash
+ollama pull nomic-embed-text
+export SESSION_RECALL_EMBED=ollama
+session-recall index
+```
+
+**你自己的端点**——任何实现 `/v1/embeddings` 的服务器（llama.cpp、vLLM、公司网关）。
+单项变量永远优先于预设，可以放心混搭：
+
+```bash
+export SESSION_RECALL_EMBED_PROVIDER=openai-compatible
+export SESSION_RECALL_EMBED_BASE_URL=https://embeddings.internal/v1
+export SESSION_RECALL_EMBED_MODEL=your-model
+export SESSION_RECALL_EMBED_DIM=1024
+```
+
+**换嵌入器就得换索引。** 向量表是定宽的，因此更换模型或维度意味着重建：删除
+`~/.local/share/session-recall/index.db` 并重新运行 `index`。Session Recall 会为每个
+已索引文件记录嵌入空间指纹，并拒绝混用不同空间——语义搜索会带着明确的提示直接关闭，
+而不是返回具有误导性的排序。
+
+<details>
+<summary><strong>模型许可说明</strong></summary>
+
+`nomic-embed-text` 之所以是本地默认，是因为它采用 Apache-2.0 许可证，而且一条命令
+就能装好。更强的小模型确实存在——`jina-embeddings-v5-text-nano` 以其体量而言得分
+高得多——但它们采用 **CC BY-NC** 许可证，任何拿它索引工作历史的人都在无人提醒的
+情况下违反条款。如果你的用途确属非商业，可把上面的变量指向这类模型。如果你的工作
+不止用英语，`qwen3-embedding:0.6b`（Apache-2.0）处理多语言历史的能力远胜 `nomic`。
+
+</details>
+
+## 保持索引新鲜
+
+如果你安装了插件，这一步已经自动处理：内置的 `SessionStart` 钩子会在每次会话启动时
+于后台运行 `session-recall index`，而增量索引让这份开销一直很低。
+
+<details>
+<summary><strong>手动注册了 MCP 服务器？自己补上钩子</strong></summary>
+
+在 `~/.claude/settings.json` 中：
+
+```json
+"hooks": {
+  "SessionStart": [
+    { "hooks": [ {
+      "type": "command",
+      "command": "sr=/abs/path/.venv/bin/session-recall; pgrep -f \"$sr index\" >/dev/null 2>&1 || (VOYAGE_API_KEY=... \"$sr\" index >/tmp/sr-index.log 2>&1 &)"
+    } ] }
+  ]
+}
+```
+
+`pgrep` 守卫可防止重复运行；`( … & )` 让进程脱离，会话启动无需等待。宿主层面的钩子
+请保持同步——shell 已经把索引器放到了后台，而且 Codex 会忽略 Claude 的 `async` 扩展。
+用 `launchd`/cron 定时器也可以。
+
+</details>
+
+## 团队模式——询问同事的历史
+
+同样的召回能力，跨越机器：与同事配对一次，你的智能体就能向对方的智能体询问
+他们过去的工作。
+
+> **你 → 同事的智能体：** 你们当时碰到 X 的本地启动问题——是怎么解决的？
+>
+> **对方的智能体** *（在同事批准答案之后）*：把配置固定到……，接着……，
+> 问题从此不再复现。
+
+过去需要一串 Slack 消息加一段记忆模糊的解释，如今变成一个问题和一个有据可依的答案。
+你永远看不到同事的原始历史——只能看到他们批准的那个答案。
+
+这里的隐私靠机制保障，而不是靠政策承诺：
+
+- 问题与答案以**端到端加密的信封**传输；中继存储的只是它自己也无法读取的盲 blob；
+- 答案由**隔离的只读 worker** 构建，范围仅限该联系人被明确授权的项目（`share allow`）；
+- 每个候选答案在离开机器之前，都要先过**机密扫描器**，再经**所有者的明确批准**
+  （Telegram 机器人，或本地执行 `share approve`）；
+- 联系人可以随时暂停（`share pause`），对等方可以随时吊销（`share revoke`）。
+
+搜索对等方的索引不需要你这边配置任何嵌入：查询以纯文本传输，由所有者的 worker
+用他们自己的提供方、对着他们自己的索引完成嵌入。
+
+<details>
+<summary><strong>选择传输方式（配对前，一次即可）</strong></summary>
+
+全新安装**不带任何传输方式**，绝不会连接你未选择的服务器。中继是盲的——它承载的
+一切都在客户端完成密封和签名——所以选哪种传输只是对等双方之间的协调问题，
+而非信任问题。
+
+**共享文件夹——零基础设施。** 一台机器上的两个账户，或任何双方都在同步的文件夹
+（Syncthing、Dropbox、NFS 挂载）：
+
+```bash
+export SESSION_RECALL_SHARE_TRANSPORT_DIR=~/Sync/sr-share   # both peers, same folder
+```
+
+**局域网内自建中继。** 一台机器运行中继，其余机器都指向它。信封无论如何都是端到端
+加密的，但这毕竟是明文 HTTP——请限制在你信任的网络内：
+
+```bash
+session-recall share relay --port 8787 --host 0.0.0.0       # on the relay machine
+export SESSION_RECALL_RELAY_URL=http://192.168.1.20:8787    # on every peer
+```
+
+**公网上自建中继。** 中继刻意只绑定 localhost，并期望前面有一个 TLS 终结器
+（Caddy 是两行配置就能搞定的选项）：
+
+```bash
+session-recall share relay --port 8787    # binds 127.0.0.1
+```
+
+```text
+relay.example.com {
+    reverse_proxy 127.0.0.1:8787
+}
+```
+
+然后在每个对等方上执行：`export SESSION_RECALL_RELAY_URL=https://relay.example.com`。
+中继只存储密封后的 blob，且邮箱在取件时即被清空。`SESSION_RECALL_RELAY_URL=none`
+可让一套安装刻意保持网络静默。把这条 `export` 写进你的 shell 配置文件，
+让智能体和定时器也能读到它。
+
+</details>
+
+<details>
+<summary><strong>配对与提问</strong></summary>
+
+配对是一次性的仪式，附带一个简短的 SAS 校验，之后提问只需一条命令：
+
+```bash
+session-recall share init            # once per device, both sides
+session-recall share invite          # you: prints a one-time code
+session-recall share join <code>     # colleague: accepts it
+session-recall share complete        # you: finish the handshake
+session-recall share trust <name>    # both: confirm the SAS matched, name the peer
+session-recall share allow <name> <project>
+session-recall share notify          # owner side: worker + approval loop
+
+session-recall share ask <name> "how did you fix the local X launch?"
+session-recall share fetch           # collect the answers
+```
+
+</details>
+
+## Meta docs——写下来的项目记忆
+
+原始召回回答的是*当时说了什么*。Meta docs 回答的是智能体在任务中途真正会问的问题：
+*这个 bug 以前修过吗？这个操作怎么做？当初为什么这么定？* 一个每日任务会把每个会话的
+对话内容——用户消息和最终回答，绝不含工具噪音——交给一个蒸馏智能体，由它在你指定的
+Git 仓库里维护 Markdown 条目：
+
+- `<project>/bugs/`——确实修复过的 bug：每个 bug 如何被识别、诊断、修复，
+  以及如何证明已修复；
+- `<project>/actions/`——按步骤写下的操作流程，再次被问到的智能体只凭条目本身
+  就能照做；
+- `<project>/decisions/`——有过争议的选择：定了什么、为何这样定、否掉了什么；
+- `USER/`——一张全局地图，记录你的信息存放在哪里以及*如何找到它*（查询命令与
+  存储位置——绝不记录存储的值本身）。
+
+```bash
+session-recall metadocs init ~/meta-docs --from-today   # memory starts now
+session-recall metadocs run                             # one pass now
+session-recall metadocs enable   # daily job: launchd (macOS) / systemd user timer (Linux)
+session-recall metadocs status
+session-recall metadocs index-history --days 30         # opt-in: distill the past, once
+```
+
+蒸馏器的全部世界只有四个 MCP 动词——`search / create / edit / delete`——而那些承重的
+规则是服务器机制，不是提示词请求：智能体没先 `search` 就调用 `create` 会被拒绝
+（去重是强制的），条目在任何字节落盘之前都会先做机密扫描，`delete` 必须给出理由。
+运行是增量式的，每个有变更的项目都会得到自己的本地提交——审阅就是看 diff，撤销就是
+revert，与团队共享这份记忆只需把仓库推到某个私有位置。除非你主动选择 `--push`，
+否则什么都不会被推送；引擎和模型只来自配置（`init --engine claude-cli|codex --model …`）——
+没有任何东西被悄悄选定。
+
+## 隐私是硬性不变量
+
+这是一个公开仓库，**里面只有代码**。运行时数据位于 `~/.local/share/session-recall/`，
+在仓库目录树之外——物理上就无法被提交。
+
+| 留在你的机器上 | 只有你主动选择才会离开 |
+|---|---|
+| Claude Code 与 Codex 的原始会话记录 | 对话表层文本 → 你配置的托管嵌入器 |
+| Cursor 的 SQLite 存储及其规范化快照 | 一条经明确批准的团队模式答案 |
+| 工具调用、输出、推理过程——完整的原始追踪 | 走内置/本地嵌入路径时——什么都不会离开 |
+| SQLite 索引与已存储的向量 | |
+
+- API 密钥只以环境变量形式存在；`.gitignore` 拦截 `.env`。
+- 测试使用合成夹具，绝不使用真实会话的片段。
+- 内置提供方让整条索引链路都留在设备上。如果你选择托管提供方，请选一个你放心
+  托付会话记录表层文本的。
+
+## 故障排查
+
+从这里开始——它会检查整条链路，并在确实出问题时以非零码退出，因此也适合放进定时器：
+
+```console
+$ session-recall health
+[ok  ] Freshness  2 minutes behind
+[warn] Embedder   responded in 5828 ms
+                  → slow provider will make indexing crawl
+[ok  ] Vector space  builtin/BAAI/bge-small-en-v1.5/384
+[ok  ] Corpus     1054 sessions (claude 373, codex 680, cursor 1)
+[ok  ] Sources    claude, codex, cursor present
+
+verdict: AMBER (voyage/voyage-4-large, index at ~/.local/share/session-recall/index.db)
+```
+
+Freshness 比较的是磁盘上最新的会话记录与索引中最新的轮次，因此一个每次会话都运行
+却每次都失败的索引器仍会显示为落后——这正是那类否则完全不可见的故障。
+
+| 症状 | 原因 / 下一步 |
+|---|---|
+| `recall_search` 的应答中 `degraded` 被置位 | 嵌入提供方不可达——只运行了字面匹配。结果是真实的，但未命中不能说明任何问题。 |
+| `degraded` 提示 “embedder changed” | 索引构建于另一个嵌入空间。运行 `session-recall index` 重新嵌入；在那之前语义排序保持关闭——这是有意为之。 |
+| 索引器日志出现带 HTML 响应体的 `HTTP code 403` | 不是你的密钥的问题：是 WAF 在拦截你的 IP（VPN 和数据中心出口很常见）。完全不带密钥时也会出现同样的 403。把出口流量改道别处，或更换提供方。 |
+| `Missing dependencies for SOCKS support` | 环境中设置了 SOCKS 代理，但该 venv 里没有安装 `PySocks`。 |
+| `recent_sessions` 显示的时间戳很旧 | 索引器最近没有成功运行过。手动运行 `session-recall index` 并阅读输出。 |
+| Cursor 使用自定义配置目录 | 设置 `SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`。 |
+
+## 开发
+
+```bash
+git clone https://github.com/AbsoluteMode/session-recall.git
+cd session-recall
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest -q
+```
+
+不用插件、改为手动注册 MCP 服务器：
+
+```bash
+claude mcp add session-recall --scope user -- /absolute/path/.venv/bin/session-recall-mcp
+```
+
+工程决策依据与不变量记录在 [`docs/decisions/`](docs/decisions/) 中。建议从这些读起：
+
+- [统一的 Claude Code + Codex 索引](docs/decisions/2026-07-10-unified-claude-codex-index.md)
+- [Cursor 作为持久的原始数据源](docs/decisions/2026-08-03-cursor-durable-raw-source.md)
+- [按项目范围的召回](docs/decisions/2026-06-26-recall-project-scope.md)
+- [P2P 分享的安全门禁](docs/decisions/2026-07-30-p2p-sharing-v1-security-gate.md)
+- [Meta docs——活的项目记忆](docs/decisions/2026-07-31-metadocs-living-project-memory.md)
+
+## 路线图
+
+- **托管/团队索引**——为团队提供一个共享索引，而不是每台机器各存一份。坦率的
+  未解问题：谁搜索谁就得嵌入查询，因此共享向量空间意味着共享嵌入链路。
+- **按联系人绕过审批**——对你完全信任的对等方跳过逐条答案审批；目前每个答案
+  都需要明确批准。
+- **更多历史来源**——Claude Code、Codex 和 Cursor 之外其他智能体的会话记录。
+
+## 参与贡献
+
+欢迎提交 issue、改进文档、编写宿主适配器和翻译。夹具请保持合成数据，绝不要提交
+真实的会话记录、索引、嵌入或凭据。
+
+<div align="center">
+  <br />
+  <strong>别再重建上下文。延续它。</strong>
+  <br />
+  <br />
+  <a href="#快速开始">立即开始</a>
+  &nbsp;·&nbsp;
+  <a href="LICENSE">MIT 许可证</a>
+</div>
diff --git a/assets/og.webp b/assets/og.webp
new file mode 100644
index 0000000..7fdf2a5
Binary files /dev/null and b/assets/og.webp differ
diff --git a/docs/README.ru.md b/docs/README.ru.md
index 7c934b9..b9a0558 100644
--- a/docs/README.ru.md
+++ b/docs/README.ru.md
@@ -1,88 +1,596 @@
-# session-recall — память для твоих кодинг-агентов
-
-*Full documentation in English: [README.md](../README.md)*
-
-Привет, ребят!
-
-Я давно делаю инструменты для себя — и вот впервые получился инструмент,
-который нашёл отклик у коллег.
-
-**session-recall** векторизует все сессии кодинг-агентов на вашей машине и
-складывает их в поисковый индекс. Это значит, что любая новая сессия может
-быстро и с высокой точностью найти информацию из любой прошлой. Индексируются
-истории Claude Code, Codex и Cursor; искать по ним может любой агент с
-поддержкой MCP.
-
-## Когда это полезно
-
-Спустя два месяца активного использования — самые живые для меня кейсы.
-
-1. **Онбординг сессии.** Новая сессия сразу в контексте:
-   - у вас несколько подписок у одного провайдера — история общая;
-   - часто меняете кодинг-агентов — Claude читает то, что вчера придумал Codex;
-   - параллельно брейнштормите/ресёрчите решения в других сессиях;
-   - нужно вернуться к задаче, которую «когда-то обсуждали».
-
-2. **Баги.** session-recall — великолепный инструмент для отлова регрессий!
-   Прежде чем чинить баг, мой агент всегда ищет: «был ли уже этот баг», «как
-   чинили», «почему посчитали, что проблема решена» — и это просто вау. Даже
-   я забываю, что подобный рецидив уже случался, а он улавливает — и понимает,
-   что нужно углубиться в компонент.
-
-3. **Действия.** Мне не приходится дважды объяснять, что именно я имею в
-   виду, когда прошу посмотреть трейс, заполнить за меня рабочие таблички,
-   разобрать распределение токенов по задаче у конкретной LLM. Любое действие,
-   которое мы однажды успешно прошли, он воспроизводит без вопросов.
-
-4. **Причинно-следственные связи.** Я говорю «давай изменим вот это решение» —
-   а он смотрит на момент, когда решение принималось, и отвечает: «так, стоп,
-   мы тогда приняли X ради совместимости с Y — прежде чем менять, надо
-   убедиться, что всё будет окей».
-
-## Team: прийти в сессию коллеги
-
-Я работаю в командах — и внедрил механизм, с которым я могу прийти в историю
-коллеги, не получив никакой личной информации, и быстро собрать нужное под
-свою задачу.
-
-Например, я пишу агенту коллеги: «когда ты столкнулся с проблемой локального
-запуска X — как ты её решил?» И через approve gate на его стороне агент
-отвечает: «нужно сделать так-то и так-то, чтобы проблема не появлялась».
-Агенты сами уточняют детали друг у друга — сложность коммуникации просто
-исчезает.
-
-Приватность здесь — механика, а не обещание: запросы летят зашифрованными
-конвертами через relay, отвечает изолированный read-only воркер строго по
-разрешённому скоупу, каждый ответ проходит сканер секретов и ваше явное
-одобрение, а любой контакт можно поставить на паузу.
-
-## meta docs: дистиллированная память проекта
-
-Сырой recall отвечает «что говорилось». А ежедневная джоба meta docs
-перегоняет каждую сессию в живые документы в git-репо:
-
-- **bugs** — как поняли, что это баг, чем лечили, как убедились, что вылечено;
-- **actions** — пошаговые процедуры, по которым агент воспроизводит действие сам;
-- **decisions** — спорные решения и почему выбрали именно так;
-- **USER** — карта, где что лежит и как это искать (только инструкции поиска,
-  никогда сами значения).
-
-Записи попадают в тот же поисковый индекс, ревью — обычный git-дифф, а
-поделиться памятью с командой = запушить репо.
-
-## Настройки
-
-- **эмбеддинг-модель** — подключаемая: без ключей используется встроенная
-  локальная ONNX-модель; Voyage даёт более точное ранжирование, также можно
-  подключить любой OpenAI-совместимый endpoint;
-- **solo / team** — можно ли устанавливать контакт с вашим MCP: share выключен
-  по умолчанию и включается явно;
-- **поисковый индекс — локальный** (SQLite на вашей машине); облачный
-  командный индекс — в планах;
-- **Cursor определяется автоматически** по стандартному локальному пути;
-  нестандартный профиль можно указать через `SESSION_RECALL_CURSOR_DB`;
-- **approve gate по контактам** — сейчас каждый исходящий ответ подтверждается
-  вручную; bypass для доверенных контактов — в будущем.
-
-Я вижу огромный потенциал в «предыдущих» пользовательских сессиях — и считаю,
-что именно они станут основой личных skills пользователей.
+<div align="center">
+
+<a href="#быстрый-старт">
+  <img src="../assets/og.webp" alt="Session Recall — ваши кодинг-агенты забывают, Session Recall — нет. Одна память для Claude Code, Codex и Cursor." width="100%" />
+</a>
+
+<br />
+<br />
+
+<strong>Общая семантическая память для Claude Code, Codex и Cursor.</strong><br />
+Найди старое решение по смыслу. Открой сырые доказательства. Продолжи работу.
+
+<br />
+<br />
+
+[![MIT License](https://img.shields.io/badge/license-MIT-b8f84f?style=flat-square&labelColor=11120f)](../LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-b8f84f?style=flat-square&labelColor=11120f)](../pyproject.toml)
+[![MCP native](https://img.shields.io/badge/MCP-native-b8f84f?style=flat-square&labelColor=11120f)](../src/session_recall/server.py)
+[![Tests](https://img.shields.io/github/actions/workflow/status/AbsoluteMode/session-recall/test.yml?branch=main&style=flat-square&label=tests&labelColor=11120f)](https://github.com/AbsoluteMode/session-recall/actions/workflows/test.yml)
+
+<br />
+
+[English](../README.md) · Русский · [Español](../README.es-ES.md) · [中文](../README.zh-CN.md)
+
+*Эталонная версия — английская; переводы могут отставать.*
+
+</div>
+
+---
+
+Кодинг-агенты помнят текущий чат. А работа живёт в месяцах чатов — возобновлённые сессии,
+параллельные подписки, worktree, разные агенты.
+
+Session Recall превращает эту историю в единый local-first индекс и отдаёт её обратно через
+пять узких MCP-инструментов. Свежая сессия может восстановить то, что вчера придумал Codex,
+и то, что Claude Code отверг три месяца назад — со ссылками на реальные реплики, вывод
+инструментов и рассуждения. Это не summary-файл, который кто-то ведёт руками: источником
+истины остаётся сам разговор.
+
+> **вы:** мы чинили конфликт auth-токенов между двумя сервисами — на чём остановились?
+>
+> **агент:** *(recall_search → expand_around)* Оба сервиса сидели на одном OAuth-аккаунте, а
+> провайдер ротирует refresh-токены на уровне аккаунта, поэтому каждый refresh инвалидировал
+> копию соседа. Патч с общей директорией кредов вы отвергли — слишком жёсткая связка — и
+> остановились на keeper-сервисе, который владеет сессией. Спека так и не была написана —
+> это и был следующий шаг.
+
+## Что это даёт
+
+| | Возможность | Что это меняет |
+|---|---|---|
+| **Одна память** | Claude Code, Codex и Cursor пополняют один индекс | Смена агента не сбрасывает историю проекта |
+| **Семантический поиск** | Поиск по смыслу, а не только по точным словам | Находятся решения, которые описать можно, а процитировать — нет |
+| **Глубокая навигация** | Открываются сырые реплики: вызовы инструментов, вывод, рассуждения | Ответ можно проверить, а не верить пересказу |
+| **Честная деградация** | Отказ семантики репортится явно | Буквальный fallback никогда не притворяется семантическим поиском |
+| **Локальность по умолчанию** | Встроенные ONNX-эмбеддинги и локальный SQLite | Старт без ключа, сервера и аккаунта |
+| **Recall со скоупом** | Фильтры по репозиторию, источнику и локальным календарным датам | Посторонние проекты не попадают в ответ |
+| **Командные ответы** | Вопрос к локальной памяти коллеги — с его одобрения | Выстраданный контекст передаётся без раскрытия сырых сессий |
+
+## Где это окупается
+
+- **Онбординг сессии.** Свежая сессия стартует уже в контексте — и при нескольких
+  параллельных подписках, и при прыжках между агентами, и при возврате к задаче, которую
+  «когда-то обсуждали».
+- **Баги и регрессии.** Прежде чем что-то чинить, агент спрашивает историю: *был ли уже этот
+  баг? как его чинили? почему поверили, что починили?* Рецидив перестаёт выглядеть свежим
+  багом — а фикс превращается из заплатки в раскопки внутри компонента.
+- **Процедуры.** Достаточно один раз объяснить процесс — как читать трейс, как разложить
+  расход токенов по задаче — и любая следующая сессия воспроизведёт его без повторного
+  инструктажа.
+- **Причинно-следственные связи.** Стоит сказать «давай изменим это решение» — и агент
+  поднимет момент, когда оно принималось: *«мы выбрали X ради совместимости с Y — прежде
+  чем менять, надо убедиться, что Y это переживёт»*.
+
+## Пять инструментов, один воркфлоу
+
+Интерфейс намеренно остаётся маленьким:
+
+| MCP-инструмент | Когда использовать |
+|---|---|
+| `recall_search(query)` | В памяти идея, а не формулировка |
+| `expand_around(session_id, uuid)` | Якорь найден, нужны доказательства вокруг него |
+| `step(session_id, uuid, direction)` | Нужна соседняя сырая реплика без нового поиска |
+| `grep(pattern)` | Известны точная ошибка, символ, путь или идентификатор |
+| `recent_sessions()` | Нужна самая свежая работа — и свежесть самого индекса |
+
+```mermaid
+flowchart LR
+    Q["describe the old problem"] --> S["recall_search"]
+    S --> A["ranked anchor"]
+    A --> E["expand_around"]
+    E --> T["step next / prev"]
+    Q -. exact identifier .-> G["grep"]
+    R["what is current?"] --> RS["recent_sessions"]
+```
+
+Каждый поисковый инструмент принимает необязательный `source` (`claude` | `codex` |
+`cursor`), `scope_cwd` — сузить выдачу до текущего репозитория (worktree схлопываются к
+корню репо) — и локальные календарные даты (`on_date` либо `start_date` / `end_date`, плюс
+`timezone` в формате IANA). Ранжированные якоря несут происхождение и человекочитаемый
+таймстемп. `grep` сканирует **все** проиндексированные транскрипты по требованию — включая
+подкапотные реплики (вывод инструментов, размышления), которые так и не стали поисковыми
+чанками. Только по требованию: никакой проактивной инъекции контекста в каждый промпт.
+
+<details>
+<summary><strong>Посмотреть полный вызов</strong></summary>
+
+```json
+{
+  "query": "why did refresh tokens conflict?",
+  "scope_cwd": "/work/keeper",
+  "source": "codex",
+  "start_date": "2026-05-01",
+  "end_date": "2026-06-30",
+  "timezone": "Europe/Moscow"
+}
+```
+
+`recall_search` отвечает `{"anchors": [...], "degraded": null | "reason"}`. Если `degraded`
+заполнен, провайдер эмбеддингов был недоступен и отработало только буквальное совпадение —
+агент может сказать об этом прямо, а не принять лексический промах за пустую историю.
+
+</details>
+
+## Быстрый старт
+
+Две части: Python-CLI (он же несёт MCP-сервер) и плагин, который подключает его к агенту.
+По времени — около двух минут плюс первый прогон индексации.
+
+### 1. Установить CLI и построить индекс
+
+```bash
+pipx install git+https://github.com/AbsoluteMode/session-recall
+session-recall setup   # one question (interaction language), then the first index
+```
+
+Ключ не нужен: без всякой настройки индексация идёт на встроенной CPU-модели — она
+скачивается один раз и выбирается по языку общения. Первый прогон проходит всю историю
+целиком: минуты на месяцы транскриптов, дальше — секунды. Скриптовая установка:
+`session-recall setup --lang en --yes`.
+
+```console
+$ session-recall index
+indexed 2175 chunks from changed transcripts
+
+your history: 1053 sessions spanning 168 days, 40,037 searchable fragments
+  Claude Code 372 · Codex 680 · Cursor 1
+  busiest: sidekey, trend_detection, glitch
+```
+
+Облачные эмбеддинги Voyage ранжируют заметно лучше встроенной модели; чтобы включить их,
+достаточно экспортировать `VOYAGE_API_KEY` до индексации — см.
+[Провайдеры эмбеддингов](#провайдеры-эмбеддингов).
+
+### 2. Подключить агентов
+
+`pipx` кладёт `session-recall` и `session-recall-mcp` в `~/.local/bin` — ровно туда, где их
+ищут манифесты плагинов.
+
+<details open>
+<summary><strong>Claude Code</strong></summary>
+
+```text
+/plugin marketplace add AbsoluteMode/session-recall
+/plugin install session-recall
+```
+
+Дальше — новая сессия: MCP-серверы, скиллы и хук SessionStart подгружаются на старте
+сессии, а не в момент установки. Хочется, чтобы агент довёл дело сам? Фраза
+`set up session-recall` (или команда `/session-recall:setup`) — и он задаст вопросы
+онбординга прямо в чате, сам выполнит команды и закончит health-проверкой и настоящим
+поиском по вашей истории.
+
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+В репозитории лежит нативный [`.codex-plugin/plugin.json`](../.codex-plugin/plugin.json) —
+готов лечь в локальное репо или личный маркетплейс; см.
+[гайд по установке локального плагина](https://learn.chatgpt.com/docs/build-plugins#install-a-local-plugin-manually).
+Codex также один раз попросит отревьюить свежеустановленные хуки через `/hooks`.
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Нужен Cursor 2.5+ (плагины появились именно там). Репозиторий подключается как маркетплейс:
+
+```bash
+cursor-agent plugin marketplace add https://github.com/AbsoluteMode/session-recall.git
+```
+
+Дальше в Cursor Agent — `/add-plugin session-recall` и одно одобрение локального stdio
+MCP-сервера, чтобы инструменты могли стартовать. Для разработки плагина запускается
+`cursor-agent --plugin-dir /absolute/path/to/session-recall` вместо установки кешированной
+копии.
+
+Cursor находится автоматически по стандартному пути данных macOS/Linux, и запущенным ему
+быть не обязательно. Portable или кастомный профиль? База указывается напрямую:
+`SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`.
+
+</details>
+
+### 3. Проверить, что работает
+
+```bash
+session-recall search "something you actually discussed last week"
+```
+
+Хиты со `score` означают, что семантический поиск жив. В агенте `claude mcp list` должен
+показывать `session-recall ✔ Connected`, а вопрос о прошлой работе — триггерить
+`recall_search`. Больше настраивать нечего: каждый плагин несёт стартовый хук своего хоста
+и переиндексирует в фоне, так что общий индекс сам поспевает за всеми тремя историями.
+
+## Как это устроено
+
+```mermaid
+flowchart TB
+    subgraph Sources["local history sources"]
+      CC["Claude Code JSONL"]
+      CX["Codex JSONL"]
+      CU["Cursor SQLite"]
+    end
+
+    CC --> I["incremental indexer"]
+    CX --> I
+    CU -->|"consistent WAL snapshot"| I
+    I --> V["conversation surface → embeddings"]
+    I --> R["raw trace, kept local"]
+    V --> DB["SQLite · sqlite-vec KNN · FTS5"]
+    R --> DB
+    DB --> MCP["five on-demand MCP tools"]
+    MCP --> A["Claude Code · Codex · Cursor · any MCP client"]
+```
+
+Эмбеддится только «поверхность» разговора — промпты пользователя и текстовые ответы
+ассистента. Вызовы инструментов, результаты, рассуждения и остальные данные трейса никогда
+не отправляются провайдеру эмбеддингов, но остаются доступными по требованию через
+`expand_around`, `step` и `grep`. Сайдчейны Claude и сессии порождённых сабагентов
+пропускаются намеренно: это подкапотная механика, а не разговор.
+
+Cursor читается из его SQLite-хранилища через online backup API, так что живая WAL-база
+снимается консистентно и без блокировки редактора. Его bubbles нормализуются в долговечные
+content-addressed JSONL-снапшоты в директории данных — глубокая навигация продолжает
+работать после того, как Cursor закрылся, обновился или был удалён.
+
+Индексация инкрементальная и дешёвая на живых транскриптах: они append-only, поэтому
+неизменённые чанки матчатся по хешу содержимого, а их векторы переиспользуются — до
+провайдера эмбеддингов доходят только новые реплики. Переезд rollout-файла Codex в архив
+тоже переиспользует его векторы. Каждый файл индексируется в собственной транзакции;
+сбойный файл логируется и повторяется на следующем прогоне, никогда не прерывая остальные.
+
+## Шпаргалка по CLI
+
+```bash
+# Refresh every history, or one source
+session-recall index
+session-recall index --source cursor
+
+# Semantic search — unified by default, scopable to a repo
+session-recall search "why did we choose the keeper service?"
+session-recall search "deployment work" --source codex --scope /work/keeper
+
+# Local calendar dates, any IANA timezone (defaults to this computer's)
+session-recall recent --date 2026-07-14
+session-recall search "deployment work" \
+  --start-date 2026-07-14 --end-date 2026-07-16 \
+  --timezone Asia/Yekaterinburg
+
+# Exact raw scan — no embedding call, caps at 100 matches by default
+session-recall grep "invalid_grant" --limit 100
+
+# Housekeeping
+session-recall prune    # drop rows for transcripts deleted from disk
+session-recall health   # the whole chain, verdict GREEN/AMBER/RED
+```
+
+`search`, `recent`, `grep` и `prune` принимают `--source claude|codex|cursor`; без него —
+единая история. Фильтры дат включительные, любую из границ можно опустить.
+
+## Провайдеры эмбеддингов
+
+Ничего не прибито к одному вендору. `SESSION_RECALL_EMBED=<preset>` задаёт endpoint,
+модель, размерность и reranker разом, потому что эти четыре параметра — не независимые
+выборы:
+
+| Пресет | Где работает | Модель | Разм. | Реранкер |
+|---|---|---|---:|---|
+| `builtin-en` | **в комплекте, бесплатно** | `bge-small-en-v1.5` | 384 | — |
+| `builtin-zh` | **в комплекте, бесплатно** | `bge-small-zh-v1.5` | 512 | — |
+| `builtin-multi` | **в комплекте, бесплатно** | `paraphrase-multilingual-MiniLM-L12-v2` | 384 | — |
+| `ollama` | **локально, бесплатно** | `nomic-embed-text` | 768 | — |
+| `lmstudio` | **локально, бесплатно** | `nomic-embed-text-v1.5` | 768 | — |
+| `voyage` | в облаке, нужен ключ | `voyage-4-large` | 1024 | `rerank-2.5` |
+| `openai` | в облаке, нужен ключ | `text-embedding-3-large` | 1024 | — |
+
+Без пресета Session Recall берёт Voyage, когда есть `VOYAGE_API_KEY`, затем пробует найти
+уже слушающий локальный сервер, а иначе запускает встроенную ONNX-модель — из коробки
+работает всегда. Встроенный вариант следует за языком общения, выбранным на онбординге
+(`SESSION_RECALL_LANG=en|zh|…`: маленький специалист по английскому или китайскому, иначе —
+мультиязычная модель). Первое использование один раз скачивает модель в директорию данных
+(70–240 МБ), дальше — CPU-инференс. Ранжирование заметно грубее облачного Voyage — это
+стартовая точка, а не потолок. Локальные пресеты идут без реранкера, так что ранжирование —
+только KNN + FTS.
+
+**Бесплатно и локально, от начала до конца:**
+
+```bash
+ollama pull nomic-embed-text
+export SESSION_RECALL_EMBED=ollama
+session-recall index
+```
+
+**Свой endpoint** — любой сервер, говорящий на `/v1/embeddings` (llama.cpp, vLLM,
+корпоративный gateway). Отдельные переменные всегда бьют пресет, так что их можно свободно
+смешивать:
+
+```bash
+export SESSION_RECALL_EMBED_PROVIDER=openai-compatible
+export SESSION_RECALL_EMBED_BASE_URL=https://embeddings.internal/v1
+export SESSION_RECALL_EMBED_MODEL=your-model
+export SESSION_RECALL_EMBED_DIM=1024
+```
+
+**Другому эмбеддеру нужен свой индекс.** Векторные таблицы фиксированной ширины, поэтому
+смена модели или размерности означает пересборку: удалить
+`~/.local/share/session-recall/index.db` и заново прогнать `index`. Session Recall снимает
+отпечаток пространства эмбеддингов у каждого проиндексированного файла и отказывается
+смешивать пространства — семантический поиск выключается с явным сообщением, вместо того
+чтобы возвращать обманчивое ранжирование.
+
+<details>
+<summary><strong>Заметки о лицензиях моделей</strong></summary>
+
+`nomic-embed-text` — локальный дефолт, потому что он под Apache-2.0 и ставится одной
+командой. Есть маленькие модели и сильнее — `jina-embeddings-v5-text-nano` для своего
+размера набирает куда больше, — но они **CC BY-NC**: индексируя рабочую историю, такую
+лицензию нарушал бы каждый, и никто бы ему об этом не сказал. Если использование
+действительно некоммерческое — можно направить переменные выше на такую модель. Если
+история не только на английском, `qwen3-embedding:0.6b` (Apache-2.0) справляется с
+мультиязычностью куда лучше `nomic`.
+
+</details>
+
+## Как индекс остаётся свежим
+
+Если установлен плагин, это уже решено: встроенный хук `SessionStart` запускает
+`session-recall index` в фоне на каждом старте сессии, а инкрементальная индексация делает
+это дёшево.
+
+<details>
+<summary><strong>MCP-сервер зарегистрирован вручную? Хук добавляется так</strong></summary>
+
+В `~/.claude/settings.json`:
+
+```json
+"hooks": {
+  "SessionStart": [
+    { "hooks": [ {
+      "type": "command",
+      "command": "sr=/abs/path/.venv/bin/session-recall; pgrep -f \"$sr index\" >/dev/null 2>&1 || (VOYAGE_API_KEY=... \"$sr\" index >/tmp/sr-index.log 2>&1 &)"
+    } ] }
+  ]
+}
+```
+
+Гард на `pgrep` не даёт прогонам накладываться; `( … & )` отцепляет процесс, чтобы старт
+сессии не ждал. Хук на уровне хоста должен оставаться синхронным — шелл и так уводит
+индексер в фон, а Codex игнорирует Claude-расширение `async`. Таймер `launchd`/cron тоже
+подходит.
+
+</details>
+
+## Командный режим — спросить историю коллеги
+
+Тот же recall, но между машинами: один раз создать пару с коллегой — и ваш агент сможет
+спрашивать его агента о его прошлой работе.
+
+> **вы → агенту коллеги:** когда ты столкнулся с проблемой локального запуска X — как ты её
+> решил?
+>
+> **его агент** *(после того как коллега одобрил ответ)*: закрепи конфиг на …, затем … — и
+> проблема больше не возвращается.
+
+То, что раньше было тредом в Slack и полузабытым объяснением, становится одним вопросом и
+одним обоснованным ответом. Сырую историю коллеги вы не видите никогда — только ответ,
+который он одобрил.
+
+Приватность здесь — механика, а не политика:
+
+- вопросы и ответы ездят **end-to-end зашифрованными конвертами**; relay хранит слепые
+  блобы, прочитать которые не может;
+- ответы собирает **изолированный read-only воркер**, ограниченный проектами, которые этому
+  контакту явно выдали (`share allow`);
+- каждый кандидат в ответ проходит **сканер секретов**, а затем **явное одобрение
+  владельца** (Telegram-бот или локально `share approve`), прежде чем покинуть машину;
+- контакт можно в любой момент поставить на паузу (`share pause`), пира — отозвать
+  (`share revoke`).
+
+Поиск по индексу пира не требует настройки эмбеддингов на вашей стороне: запрос едет
+текстом, а воркер владельца эмбеддит его своим провайдером по своему индексу.
+
+<details>
+<summary><strong>Выбрать транспорт (один раз, до пейринга)</strong></summary>
+
+У свежей установки **нет транспорта**, и она никогда не ходит на сервер, который вы не
+выбирали. Relay слепой — всё, что он переносит, запечатано и подписано на клиентах, — так
+что выбор транспорта — это координация между пирами, а не вопрос доверия.
+
+**Общая папка — ноль инфраструктуры.** Два аккаунта на одной машине или любая папка,
+которую синхронизируют оба пира (Syncthing, Dropbox, NFS-маунт):
+
+```bash
+export SESSION_RECALL_SHARE_TRANSPORT_DIR=~/Sync/sr-share   # both peers, same folder
+```
+
+**Свой relay в LAN.** Одна машина его запускает, все остальные на него смотрят. Конверты в
+любом случае зашифрованы end-to-end, но это голый HTTP — пускать его стоит только в сеть,
+которой вы доверяете:
+
+```bash
+session-recall share relay --port 8787 --host 0.0.0.0       # on the relay machine
+export SESSION_RECALL_RELAY_URL=http://192.168.1.20:8787    # on every peer
+```
+
+**Свой relay в интернете.** Relay нарочно биндится на localhost и ждёт перед собой
+TLS-терминатор (Caddy — вариант в две строки):
+
+```bash
+session-recall share relay --port 8787    # binds 127.0.0.1
+```
+
+```text
+relay.example.com {
+    reverse_proxy 127.0.0.1:8787
+}
+```
+
+Затем на каждом пире: `export SESSION_RECALL_RELAY_URL=https://relay.example.com`. Relay
+хранит только запечатанные блобы, а mailbox опустошается при fetch.
+`SESSION_RECALL_RELAY_URL=none` намеренно держит установку в сетевом молчании. `export`
+стоит положить в профиль шелла, чтобы агенты и таймеры тоже его видели.
+
+</details>
+
+<details>
+<summary><strong>Пейринг и вопросы</strong></summary>
+
+Пейринг — одноразовая церемония с короткой SAS-проверкой, дальше вопрос — одна команда:
+
+```bash
+session-recall share init            # once per device, both sides
+session-recall share invite          # you: prints a one-time code
+session-recall share join <code>     # colleague: accepts it
+session-recall share complete        # you: finish the handshake
+session-recall share trust <name>    # both: confirm the SAS matched, name the peer
+session-recall share allow <name> <project>
+session-recall share notify          # owner side: worker + approval loop
+
+session-recall share ask <name> "how did you fix the local X launch?"
+session-recall share fetch           # collect the answers
+```
+
+</details>
+
+## Meta docs — память проекта, записанная текстом
+
+Сырой recall отвечает, *что говорилось*. Meta docs отвечает на то, что агенты реально
+спрашивают посреди задачи: *этот баг уже чинили? как выполнить это действие? почему решили
+именно так?* Ежедневная джоба отдаёт диалог каждой сессии — сообщения пользователя и
+финальные ответы, никогда шум инструментов — агенту-дистиллятору, который ведёт
+Markdown-записи в выбранном Git-репозитории:
+
+- `<project>/bugs/` — реально починенные баги: как баг распознали, как диагностировали, чем
+  чинили и как доказали, что починено;
+- `<project>/actions/` — процедуры, шаг за шагом, написанные так, чтобы агент, которого
+  попросили снова, справился по одной записи;
+- `<project>/decisions/` — спорные выборы: что решили, почему именно так и что отвергли;
+- `USER/` — глобальная карта: где живёт ваша информация и *как её найти* (команды поиска и
+  места хранения — никогда сами значения).
+
+```bash
+session-recall metadocs init ~/meta-docs --from-today   # memory starts now
+session-recall metadocs run                             # one pass now
+session-recall metadocs enable   # daily job: launchd (macOS) / systemd user timer (Linux)
+session-recall metadocs status
+session-recall metadocs index-history --days 30         # opt-in: distill the past, once
+```
+
+Весь мир дистиллятора — четыре MCP-глагола: `search / create / edit / delete`, а несущие
+правила — это механика сервера, а не просьбы в промпте: `create` отклоняется, пока агент не
+сделал `search` (дедупликация обязательна), записи сканируются на секреты до того, как хоть
+байт коснётся диска, а `delete` требует причину. Прогоны инкрементальные, и каждый
+изменённый проект получает свой локальный коммит — ревью это дифф, откат это revert, а
+поделиться памятью с командой — значит просто запушить репо в приватное место. Ничего не
+пушится без явного `--push`; движок и модель берутся только из конфига
+(`init --engine claude-cli|codex --model …`) — ничего не выбирается втихую.
+
+## Приватность — жёсткий инвариант
+
+Это публичный репозиторий. **В него попадает только код.** Рантайм-данные живут в
+`~/.local/share/session-recall/`, вне дерева репо — их физически нельзя закоммитить.
+
+| Остаётся на вашей машине | Уходит только по вашему выбору |
+|---|---|
+| Оригинальные транскрипты Claude Code и Codex | Текст поверхности разговора → настроенный вами облачный эмбеддер |
+| SQLite-хранилище Cursor и его нормализованные снапшоты | Явно одобренный ответ командного режима |
+| Вызовы инструментов, вывод, рассуждения — весь сырой трейс | Ничего — на встроенном/локальном пути эмбеддингов |
+| SQLite-индекс и сохранённые векторы | |
+
+- API-ключи — только переменные окружения; `.gitignore` блокирует `.env`.
+- Тесты используют синтетические фикстуры и никогда — реальный кусок сессии.
+- Встроенный провайдер держит весь путь индексации на устройстве. Если выбран облачный —
+  это должен быть тот, кому вы доверяете текст поверхности своих транскриптов.
+
+## Диагностика
+
+Начинать отсюда: команда проверяет всю цепочку и выходит с ненулевым кодом, когда что-то
+действительно сломано, — поэтому годится и для таймера:
+
+```console
+$ session-recall health
+[ok  ] Freshness  2 minutes behind
+[warn] Embedder   responded in 5828 ms
+                  → slow provider will make indexing crawl
+[ok  ] Vector space  builtin/BAAI/bge-small-en-v1.5/384
+[ok  ] Corpus     1054 sessions (claude 373, codex 680, cursor 1)
+[ok  ] Sources    claude, codex, cursor present
+
+verdict: AMBER (voyage/voyage-4-large, index at ~/.local/share/session-recall/index.db)
+```
+
+Freshness сравнивает самый свежий транскрипт на диске с самой свежей репликой в индексе,
+поэтому индексер, который запускается на каждой сессии и каждый раз падает, всё равно
+отображается отстающим — ровно тот сбой, который иначе невидим.
+
+| Симптом | Причина / что делать |
+|---|---|
+| `recall_search` отвечает с заполненным `degraded` | Провайдер эмбеддингов недоступен — отработало только буквальное совпадение. Результаты настоящие, но промах ничего не доказывает. |
+| `degraded` говорит «embedder changed» | Индекс построен в другом пространстве эмбеддингов. Прогнать `session-recall index`, чтобы переэмбеддить; до этого семантическое ранжирование выключено — намеренно. |
+| Индексер логирует `HTTP code 403` с HTML-телом | Дело не в ключе: WAF режет ваш IP (типично для VPN и датацентровых выходов). Тот же 403 приходит и вовсе без ключа. Вывести трафик другим путём или сменить провайдера. |
+| `Missing dependencies for SOCKS support` | В окружении задан SOCKS-прокси, а `PySocks` в этом venv не установлен. |
+| `recent_sessions` показывает старый таймстемп | Индексер давно не завершался успешно. Запустить `session-recall index` руками и прочитать вывод. |
+| Cursor живёт в кастомном профиле | Задать `SESSION_RECALL_CURSOR_DB=/path/to/User/globalStorage/state.vscdb`. |
+
+## Разработка
+
+```bash
+git clone https://github.com/AbsoluteMode/session-recall.git
+cd session-recall
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest -q
+```
+
+Чтобы зарегистрировать MCP-сервер вручную, минуя плагин:
+
+```bash
+claude mcp add session-recall --scope user -- /absolute/path/.venv/bin/session-recall-mcp
+```
+
+Инженерные обоснования и инварианты живут в [`docs/decisions/`](decisions/). Начать стоит
+с этих:
+
+- [Единый индекс Claude Code + Codex](decisions/2026-07-10-unified-claude-codex-index.md)
+- [Cursor как долговечный сырой источник](decisions/2026-08-03-cursor-durable-raw-source.md)
+- [Recall со скоупом проекта](decisions/2026-06-26-recall-project-scope.md)
+- [Security gate для P2P-шаринга](decisions/2026-07-30-p2p-sharing-v1-security-gate.md)
+- [Meta docs — живая память проекта](decisions/2026-07-31-metadocs-living-project-memory.md)
+
+## Роадмап
+
+- **Облачный / командный индекс** — один общий индекс на команду вместо копий на каждой
+  машине. Честный открытый вопрос: тот, кто ищет, должен заэмбеддить запрос, так что общее
+  векторное пространство подразумевает общий путь эмбеддингов.
+- **Bypass одобрения по контактам** — пропуск поштучного одобрения для полностью доверенных
+  пиров; сегодня каждый ответ одобряется явно.
+- **Больше историй** — транскрипты других агентов, помимо Claude Code, Codex и Cursor.
+
+## Контрибьютинг
+
+Issues, улучшения документации, адаптеры хостов и переводы — добро пожаловать. Фикстуры —
+только синтетические; реальные транскрипты, индексы, эмбеддинги и креды не коммитятся
+никогда.
+
+<div align="center">
+  <br />
+  <strong>Хватит пересобирать контекст. Продолжи работу.</strong>
+  <br />
+  <br />
+  <a href="#быстрый-старт">Начать</a>
+  &nbsp;·&nbsp;
+  <a href="../LICENSE">Лицензия MIT</a>
+</div>