Skip to content
Back to search

episteme

MarketplaceWorks with Claude CodeGitHub

Marketplace de episteme: el plugin con sus skills.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bajmein--episteme/badge.svg)](/listings/bajmein--episteme)

HTML

<a href="/listings/bajmein--episteme"><img src="/api/listings/bajmein--episteme/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines
  1. {
  2. "name": "episteme",
  3. "owner": { "name": "Bajmein" },
  4. "description": "Marketplace de episteme: el plugin con sus skills.",
  5. "plugins": [
  6. {
  7. "name": "episteme",
  8. "source": "./plugin",
  9. "license": "MIT",
  10. "description": "Skills de episteme: conectar un proyecto, pausar y retomar una tarea, mantención de memorias, recordatorios y scaffolding (README, CLAUDE.md, CHANGELOG, .github y reglas)."
  11. }
  12. ]
  13. }
README.md · README · 239 lines
  1. <div align="center">
  2. ![episteme: Agentic Memory & Knowledge Vault. Persistent Knowledge Engine for AI Workflows.](static/banner-episteme.jpg)
  3. <a href="https://github.com/Bajmein/episteme/tags"><img alt="Versión" src="https://img.shields.io/badge/versi%C3%B3n-v0.13.2-8B5CF6?style=for-the-badge"></a>
  4. <a href="https://www.python.org/"><img alt="Python" src="https://img.shields.io/badge/python-3.14+-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54"></a>
  5. <a href="https://docs.astral.sh/uv/"><img alt="uv" src="https://img.shields.io/badge/uv-DE5FE9?style=for-the-badge&logo=uv&logoColor=white"></a>
  6. <a href="https://github.com/modelcontextprotocol/python-sdk"><img alt="MCP SDK" src="https://img.shields.io/badge/MCP_SDK-2.x-005571?style=for-the-badge&logo=modelcontextprotocol&logoColor=white"></a>
  7. <a href="https://www.sqlite.org/fts5.html"><img alt="SQLite FTS5" src="https://img.shields.io/badge/sqlite-FTS5-07405e?style=for-the-badge&logo=sqlite&logoColor=white"></a>
  8. <a href="https://obsidian.md/"><img alt="Obsidian" src="https://img.shields.io/badge/Obsidian-483699?style=for-the-badge&logo=obsidian&logoColor=white"></a>
  9. <a href="https://www.markdownguide.org/"><img alt="Markdown" src="https://img.shields.io/badge/markdown-000000?style=for-the-badge&logo=markdown&logoColor=white"></a>
  10. <a href="https://codescene.io/projects/87754"><img alt="CodeScene" src="https://img.shields.io/badge/CodeScene-analyzed-5F46EB?style=for-the-badge"></a>
  11. <a href="LICENSE"><img alt="Licencia MIT" src="https://img.shields.io/badge/licencia-MIT-yellow?style=for-the-badge"></a>
  12. <br>
  13. <a href="#instalación"><img alt="Linux" src="https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black"></a>
  14. <a href="#instalación"><img alt="macOS" src="https://img.shields.io/badge/mac%20os-000000?style=for-the-badge&logo=macos&logoColor=F0F0F0"></a>
  15. <a href="#instalación"><img alt="Windows" src="https://img.shields.io/badge/Windows-0078D6?style=for-the-badge"></a>
  16. <br>
  17. <a href="https://github.com/Bajmein/episteme/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Bajmein/episteme/actions/workflows/ci.yml/badge.svg?branch=main" height="24"></a>
  18. # episteme
  19. **Documentación y memoria de proyectos para agentes, servida por MCP desde un vault Markdown**
  20. </div>
  21. <p align="center">
  22. <a href="#qué-es">Qué es</a> ·
  23. <a href="#cómo-funciona">Cómo funciona</a> ·
  24. <a href="#instalación">Instalación</a> ·
  25. <a href="#uso-diario">Uso diario</a> ·
  26. <a href="#las-12-herramientas">Herramientas</a> ·
  27. <a href="#límites">Límites</a> ·
  28. <a href="#documentación">Documentación</a>
  29. </p>
  30. ---
  31. ## Qué es
  32. Claude Code es como un colega brillante que cada mañana llega sin recordar nada de ayer.
  33. Claude Code empieza cada sesión sin recordar la anterior. **episteme le da una memoria que dura**: una carpeta de notas en Markdown (el *vault*) donde quedan las decisiones, las lecciones y la documentación de tus proyectos, y que Claude consulta y completa mientras trabaja.
  34. | | Qué hace por ti |
  35. | :-- | :-- |
  36. | **Recuerda** | Guarda decisiones, lecciones, errores y preferencias como notas ordenadas por proyecto |
  37. | **Encuentra** | Busca en todo el vault, en español, sin distinguir mayúsculas ni tildes |
  38. | **Avisa a tiempo** | Antes de editar un archivo, muestra las normas que le aplican; después, lo que ya se sabe de él |
  39. | **Retoma** | Guarda en qué ibas antes de que la conversación se compacte y lo recupera después |
  40. | **Mantiene la documentación al día** | Con `/episteme:docs`, baja las páginas de la documentación de terceros guardada en el vault y actualiza solo las que cambiaron |
  41. | **Cuida el orden** | Detecta duplicados, memorias vencidas, enlaces rotos y memorias sin enlazar; rechaza guardar contraseñas y tokens |
  42. Las notas son archivos de texto tuyos: se abren con [Obsidian](https://obsidian.md/) o con cualquier editor, y no dependen de ningún servicio externo.
  43. > [!NOTE]
  44. > **Versión actual: v0.13.2.** Funciona en Linux, macOS y Windows. Las novedades de cada versión están en el [CHANGELOG](CHANGELOG.md).
  45. ## Cómo funciona
  46. <p align="center">
  47. <img src="static/diagrams/arquitectura.png" alt="Claude Code (el agente y sus hooks) llama al servidor episteme, que lee y escribe las notas Markdown del vault y mantiene un índice de búsqueda; Obsidian puede abrir el mismo vault" width="880">
  48. </p>
  49. 1. **Claude Code** habla con episteme de dos formas: el agente usa sus herramientas cuando las necesita, y los *hooks* las llaman solos en momentos fijos de la sesión.
  50. 2. **episteme** es un programa pequeño que corre en tu máquina. Es la única puerta al vault: valida lo que se guarda y mantiene un índice para buscar rápido.
  51. 3. **El vault** es una carpeta de notas Markdown, por defecto `~/.episteme`. Tú puedes leerlo y editarlo con Obsidian.
  52. <details>
  53. <summary><b>Glosario rápido</b></summary>
  54. | Término | Qué significa |
  55. | :-- | :-- |
  56. | **Vault** | La carpeta con todas las notas. Se divide en zonas: documentación, memorias, planes |
  57. | **Memoria** | Una nota corta con algo que vale la pena recordar: una decisión, una lección, un recordatorio |
  58. | **Herramienta (tool)** | Una acción que Claude puede pedirle a episteme: buscar, leer, guardar |
  59. | **Hook** | Un automatismo de Claude Code que llama a una herramienta sin que nadie lo pida |
  60. | **MCP** | El protocolo estándar con el que Claude Code se conecta a programas como episteme |
  61. </details>
  62. ## Instalación
  63. **Necesitas** [uv](https://docs.astral.sh/uv/) y git. uv consigue Python por ti si falta.
  64. ### Opción A · Con la skill (recomendada)
  65. Las skills vienen en un plugin de Claude Code. Se instala una vez por máquina, con dos comandos (igual en Linux, macOS y Windows):
  66. ```bash
  67. claude plugin marketplace add Bajmein/episteme
  68. claude plugin install episteme@episteme
  69. ```
  70. Más detalles (actualizar, quitar) en la [guía de instalación](docs/instalacion.md#el-plugin).
  71. Después, en cada proyecto que quieras conectar:
  72. 1. Reinicia Claude Code y ábrelo en la raíz del proyecto.
  73. 2. Escribe `/episteme:setup`.
  74. 3. Aprueba los cambios que te muestra. La skill registra el servidor, configura los hooks y los permisos, y añade la regla al `CLAUDE.md`.
  75. El plugin trae además estas skills:
  76. | Skill | Para qué |
  77. | :-- | :-- |
  78. | `/episteme:pausa` | Guardar en qué estabas antes de `/clear` o de cerrar, y retomarlo después con `/episteme:pausa retomar` |
  79. | `/episteme:mantencion` | Revisar las memorias contigo: unificar las repetidas, resolver contradicciones y archivar lo vencido. Con `corta` hace una ronda rápida de 3 casos; con `huerfanas`, enlaza las memorias que quedaron sueltas |
  80. | `/episteme:reminder <texto>` | Dejar un recordatorio que sale al empezar cada sesión del proyecto |
  81. | `/episteme:scaffold` | Crear o revisar la base del proyecto: `README.md`, `CLAUDE.md`, `CHANGELOG.md`, las reglas para contribuir y el `.gitignore`. Con `auditar` solo revisa, sin cambiar nada. También avisa cuando el README o el `CLAUDE.md` llevan tiempo sin revisar |
  82. | `/episteme:docs [suite]` | Poner al día la documentación de terceros guardada en `docs/` del vault (todas las suites, o solo la que nombres, como `claude code`): baja las páginas, muestra qué cambió y lo guarda |
  83. ### Opción B · A mano
  84. Un solo comando registra el servidor. Cambia `<proyecto>` por el nombre del tuyo.
  85. **Linux y macOS**
  86. ```bash
  87. claude mcp add --scope local episteme -- \
  88. uvx --from git+https://github.com/Bajmein/episteme@v0.13.2 episteme --project <proyecto>
  89. ```
  90. **Windows** (PowerShell, en una sola línea)
  91. ```powershell
  92. claude mcp add --scope local episteme -- uvx --from git+https://github.com/Bajmein/episteme@v0.13.2 episteme --project <proyecto>
  93. ```
  94. Luego faltan los hooks, los permisos y la regla del `CLAUDE.md`: los pasos están en la [guía de instalación](docs/instalacion.md#después-de-registrar).
  95. > [!TIP]
  96. > Para comprobar que quedó bien, `claude mcp list` debe mostrar `episteme` conectado. La primera vez tarda un poco, porque se descarga. Para actualizar, repite el registro con el tag nuevo.
  97. ## Uso diario
  98. No hay comandos que aprender: se usa conversando con Claude.
  99. | Tú | episteme |
  100. | :-- | :-- |
  101. | Empiezas una sesión | Le entrega a Claude las normas del proyecto, los recordatorios vencidos y las memorias más importantes |
  102. | Escribes un mensaje | Sugiere las memorias que vienen al caso |
  103. | Dices «recuerda que…» | Guarda una memoria nueva, salvo que ya exista una casi igual |
  104. | Preguntas «¿qué decidimos sobre…?» | Claude busca en el vault antes de responder |
  105. | Claude va a editar un archivo | Le muestra las normas que aplican a ese archivo |
  106. | La conversación se compacta o la limpias con `/clear` | Al compactar guarda el estado del trabajo; en los dos casos lo recupera al seguir |
  107. ### Lo que pasa solo en cada sesión
  108. <p align="center">
  109. <img src="static/diagrams/hooks-sesion.png" alt="Secuencia de una sesión: al enviar un mensaje, antes y después de usar un archivo, al compactar o limpiar la conversación, Claude Code llama a una herramienta de episteme y recibe contexto" width="880">
  110. </p>
  111. Los hooks nunca bloquean a Claude ni deciden por él: solo le acercan contexto. Funcionan como un semáforo, no como un muro: Claude puede leer la norma y aun así equivocarse. La configuración está en [Hooks](docs/hooks.md).
  112. #### Quién hace qué y cuándo
  113. | Cuándo | Quién | Qué pasa |
  114. | :-- | :-- | :-- |
  115. | Al escribir un mensaje | hook | La primera vez entrega la bienvenida; después sugiere memorias que vienen al caso |
  116. | Antes de editar un archivo | hook | Muestra las normas de ese archivo. No pausa ni bloquea la edición |
  117. | Después de leer o editar un archivo | hook | Muestra lo que ya se sabe de él |
  118. | Al compactar o con `/clear` | hook | Al compactar guarda el estado del trabajo; después de compactar o de `/clear`, lo recupera |
  119. | En la primera bienvenida, como mucho una vez por periodo | episteme | Avisa de lo pendiente de revisar y propone una ronda corta; si lo activas, archiva lo vencido y hace un backup |
  120. | Cuando lo necesita | Claude | Busca, lee, guarda («recuerda que…») y corrige memorias |
  121. | Cuando tú lo pides | tú | `/episteme:mantencion` para revisar y ordenar |
  122. Guardar una memoria siempre lo decide Claude: ningún hook copia lo que escribes. episteme no revisa el vault en segundo plano: la revisión corre cuando alguien la pide.
  123. ## Las 12 herramientas
  124. | Herramienta | Para qué sirve | Escribe |
  125. | :-- | :-- | :-: |
  126. | `search` | Buscar en las notas y las memorias | |
  127. | `read` | Leer una nota, una sección o varias notas a la vez | |
  128. | `links` | Ver qué notas enlazan con otra | |
  129. | `context` | Dar la bienvenida de la sesión y reunir lo relevante para una tarea | ● |
  130. | `surface` | Mostrar lo que se sabe de un archivo | |
  131. | `constraints` | Mostrar las normas que aplican a un archivo | |
  132. | `remember` | Guardar una memoria nueva; avisa si le faltan palabras clave o enlaces | ● |
  133. | `revise` | Corregir, reemplazar o archivar una nota | ● |
  134. | `review` | Revisar el vault: duplicados, vencidas, enlaces rotos y memorias sueltas, con sugerencias de a qué enlazarlas | |
  135. | `checkpoint` | Guardar y recuperar el estado del trabajo | ● |
  136. | `docs_status` | Ver las suites de documentación y qué páginas tienen | |
  137. | `docs_write` | Guardar una página de documentación descargada (lo usa `/episteme:docs`) | ● |
  138. Los parámetros y el comportamiento exacto de cada una están en [Tools y memorias](docs/tools.md).
  139. ### Tipos de memoria
  140. | Tipo | Qué guarda |
  141. | :-- | :-- |
  142. | `decision` | Algo que se decidió y por qué |
  143. | `constraint` | Una norma que hay que respetar al tocar ciertos archivos |
  144. | `lesson` | Algo aprendido que conviene repetir o evitar |
  145. | `error` | Un fallo y cómo se resolvió |
  146. | `preference` | Cómo le gusta trabajar a la persona |
  147. | `insight` | Un hallazgo o una conclusión |
  148. | `reminder` | Algo pendiente, con fecha |
  149. | `session` | El estado del trabajo, guardado al compactar |
  150. Cada memoria lleva una prioridad del 1 al 5: las de prioridad 5 son las normas que Claude ve al empezar cada sesión.
  151. ## Límites
  152. - **Busca por palabras, no por significado.** «marketing» no encuentra una nota que solo dice «mkt». Por eso cada memoria lleva `keywords` con sinónimos y siglas, que Claude añade al guardar.
  153. - **Avisa, no obliga.** Las normas llegan a Claude a tiempo, pero nada le impide ignorarlas.
  154. - **No se ordena solo.** Unificar memorias repetidas y resolver contradicciones lo apruebas tú, con `/episteme:mantencion`. Conviene activar `archive_expired = true` (ver [Mantención](docs/mantencion.md)).
  155. - **El filtro de contraseñas conoce los formatos habituales.** Una clave con un formato raro puede pasar: no dictes secretos.
  156. ## Documentación
  157. El detalle técnico vive en [`docs/`](docs/):
  158. | Documento | Contenido |
  159. | :-- | :-- |
  160. | [Instalación](docs/instalacion.md) | Pasos a mano en Linux, macOS y Windows, y el plugin con las skills |
  161. | [Configuración](docs/configuracion.md) | Argumentos del servidor, variables, `episteme.toml`, zonas y registro de actividad |
  162. | [Tools y memorias](docs/tools.md) | Las 12 herramientas con sus parámetros, el esquema de las memorias y los errores |
  163. | [Suites de documentación](docs/documentacion.md) | La documentación de terceros en `docs/` del vault y cómo se mantiene al día con `/episteme:docs` |
  164. | [Hooks](docs/hooks.md) | El bloque para `settings.json`, los permisos recomendados y cómo comprobar que funcionan |
  165. | [Mantención](docs/mantencion.md) | Avisos, archivado de memorias vencidas, backup y el ciclo de revisión |
  166. | [Migración de OMEGA](docs/migracion-omega.md) | Cómo traer las memorias de OMEGA |
  167. | [Desarrollo](docs/desarrollo.md) | Tests, lint, salud del código y scripts de medición |
  168. | [CHANGELOG](CHANGELOG.md) | Cambios de cada versión |
  169. ## Desarrollo
  170. ```bash
  171. uv sync # instala las dependencias
  172. uv run ruff check # lint
  173. uv run pytest # tests
  174. ```
  175. El resto (el lint completo del CI, la revisión de calidad de cada PR con CodeScene y los scripts de medición) está en [Desarrollo](docs/desarrollo.md).
  176. ## Licencia
  177. [MIT](LICENSE), © 2026 Benjamín Criado.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.