Skip to content
Back to search

shiori

Shiori (栞): Shared memory and Markdown notes for all your AI agents. Self-hosted MCP server with binary-tree episodic memory, hybrid search, Git history, and OAuth 2.1.

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/8bury--shiori/badge.svg)](/listings/8bury--shiori)

HTML

<a href="/listings/8bury--shiori"><img src="/api/listings/8bury--shiori/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Create a GitHub OAuth App** (*Settings → Developer settings → OAuth Apps*): - **Homepage URL:** `https://shiori.yourdomain.com` - **Authorization callback URL:** `https://shiori.yourdomain.com/callback` 2. **Deploy in Coolify** (or any Docker host): - Point a new resource at `8bury/shiori` using the `Dockerfile`. - Mount a persistent volume at `/data` (stores `/data/notes`, `/data/shiori.db`, and `/data/memory.log`). - Set your domain (`https://shiori.yourdomain.com`). Coolify/Traefik handles HTTPS and checks `/health`. 3. **Configure environment variables** (see [.env.example](.env.example)): - `PUBLIC_URL`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `OWNER_GITHUB_ID` - `ADMIN_SECRET` (random hex string for `/admin/*`) - `EMBEDDING_PROVIDER` (`openai`, `gemini`, or `none`) and `EMBEDDING_API_KEY` - `ALLOWED_REDIRECT_PREFIXES` (comma-separated callback prefixes for extra clients like Muse or Grok; Claude, ChatGPT, and localhost are allowed by default)

Full setup, importing existing notes, and operations: [docs/setup.md](docs/setup.md).

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.

README.md · README · 117 lines
  1. # Shiori (栞)
  2. <p align="center">
  3. <a href="https://github.com/8bury/shiori/actions/workflows/ci.yml"><img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/8bury/shiori/ci.yml?branch=main&style=flat-square&label=tests&labelColor=1B2632"></a>
  4. <img alt="Node.js 24" src="https://img.shields.io/badge/runtime-Node.js_24-339933?style=flat-square&labelColor=1B2632&logo=node.js&logoColor=white">
  5. <img alt="MCP" src="https://img.shields.io/badge/protocol-MCP-5A4BD1?style=flat-square&labelColor=1B2632">
  6. <img alt="OAuth 2.1" src="https://img.shields.io/badge/auth-OAuth_2.1-2F8A5B?style=flat-square&labelColor=1B2632">
  7. <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-8A6A3F?style=flat-square&labelColor=1B2632"></a>
  8. </p>
  9. **Shared memory and Markdown notes for all your AI agents.**
  10. *Shiori* (栞, *bookmark / trail marker*) is a self-hosted remote MCP server that lets **Muse**, **Grok**, **Claude**, **ChatGPT**, and your local coding agents share the same context. Start a conversation in one agent and pick it up in another without repeating yourself.
  11. ## How it works
  12. ![Shiori Architecture](docs/diagrams/architecture.svg)
  13. Shiori runs as a single lightweight **Node 24 + SQLite + Git** container with two complementary layers:
  14. 1. **Episodic Memory Tree:** An append-only timeline of 1-line facts, preferences, and decisions, organized into a binary tree of summaries. When any agent starts a session (`memory_wake`), it gets recent memories verbatim and older memories exponentially compressed inside a fixed token budget, and can drill down (`memory_zoom`) or search (`memory_recall`) anytime.
  15. 2. **Long-form Notes:** Editable Markdown documents backed by a real Git repository (every edit is a commit, nothing is ever lost) with hybrid search combining SQLite FTS5 keywords and API embeddings (OpenAI, Gemini, or keyword-only).
  16. 3. **Zero-trust OAuth 2.1:** Every client authenticates via OAuth 2.1 + GitHub sign-in restricted to your numeric `OWNER_GITHUB_ID`, with a consent screen, PKCE S256, redirect allowlist, and per-client grant revocation.
  17. ![Binary-Tree Episodic Memory](docs/diagrams/memory-tree.svg)
  18. See [ARCHITECTURE.md](ARCHITECTURE.md) for the OAuth 2.1 and hybrid search flow diagrams.
  19. ## Quick start (Coolify / Docker)
  20. 1. **Create a GitHub OAuth App** (*Settings → Developer settings → OAuth Apps*):
  21. - **Homepage URL:** `https://shiori.yourdomain.com`
  22. - **Authorization callback URL:** `https://shiori.yourdomain.com/callback`
  23. 2. **Deploy in Coolify** (or any Docker host):
  24. - Point a new resource at `8bury/shiori` using the `Dockerfile`.
  25. - Mount a persistent volume at `/data` (stores `/data/notes`, `/data/shiori.db`, and `/data/memory.log`).
  26. - Set your domain (`https://shiori.yourdomain.com`). Coolify/Traefik handles HTTPS and checks `/health`.
  27. 3. **Configure environment variables** (see [.env.example](.env.example)):
  28. - `PUBLIC_URL`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `OWNER_GITHUB_ID`
  29. - `ADMIN_SECRET` (random hex string for `/admin/*`)
  30. - `EMBEDDING_PROVIDER` (`openai`, `gemini`, or `none`) and `EMBEDDING_API_KEY`
  31. - `ALLOWED_REDIRECT_PREFIXES` (comma-separated callback prefixes for extra clients like Muse or Grok; Claude, ChatGPT, and localhost are allowed by default)
  32. Full setup, importing existing notes, and operations: [docs/setup.md](docs/setup.md).
  33. ## Local development
  34. ```sh
  35. npm ci
  36. cp .env.example .env
  37. npm run dev
  38. ```
  39. Run checks:
  40. ```sh
  41. npm run lint
  42. npm run typecheck
  43. npm run build
  44. npm test
  45. ```
  46. ## Connecting your agents
  47. - **Claude Code:**
  48. ```sh
  49. claude mcp add -s user --transport http shiori https://shiori.yourdomain.com/mcp
  50. ```
  51. - **Muse, Grok, Claude (web/desktop/mobile), ChatGPT:** add a custom remote MCP connector pointing to `https://shiori.yourdomain.com/mcp`.
  52. - If a new client gets a `403` during sign-in, check the container logs for `{"auth":"redirect refused","redirectUri":"..."}` and add its callback prefix to `ALLOWED_REDIRECT_PREFIXES`.
  53. - **Agent instructions:** Shiori sends usage instructions automatically via MCP server `instructions`. For best results, also paste [MEMORY_PROMPT.md](MEMORY_PROMPT.md) into your `AGENTS.md` / `CLAUDE.md` or custom instructions in Muse and Grok.
  54. ## Web viewer
  55. Open `https://shiori.yourdomain.com/ui` and sign in with GitHub (same OAuth App, same `OWNER_GITHUB_ID` check) to browse your memory timeline, notes, and summaries, and search across both. The viewer is read-only; sessions last 7 days.
  56. ## MCP Tools
  57. ### Episodic Memory Tree
  58. | Tool | Description |
  59. |---|---|
  60. | `memory_wake` | Read the logarithmic timeline (recent verbatim, older summarized) at session start |
  61. | `memory_note` | Record a 1-line memory (<= 280 bytes); tree compaction runs automatically in the background when a summary LLM is configured |
  62. | `memory_zoom` | Open a `#lo-hi` summary node into its two halves down to raw memories |
  63. | `memory_nap` | *(Fallback only, registered when `MEMORY_SUMMARY_PROVIDER=none`)* Save a 1-line summary for a pending `#lo-hi` range |
  64. ### Unified Search
  65. | Tool | Description |
  66. |---|---|
  67. | `search` | Search both episodic memories (FTS5 + substring fallback; opt-in safe regex) and long-form notes (hybrid FTS5 + vector search) in separate sections, or filter with `scope` |
  68. ### Long-form Notes
  69. | Tool | Description |
  70. |---|---|
  71. | `list_notes` | List Markdown note paths (optional prefix filter) |
  72. | `read_note` | Read a note and its version hash |
  73. | `write_note` | Create or overwrite a note (with optimistic version check) |
  74. | `edit_note` | Replace an exact passage in a note |
  75. | `delete_note` | Delete a note (recoverable in Git history) |
  76. | `move_note` | Move or rename a note in one commit |
  77. ## Admin endpoints
  78. Protected by `Authorization: Bearer <ADMIN_SECRET>`:
  79. - `GET /admin/grants`: list active OAuth client grants
  80. - `DELETE /admin/grants/<id>`: revoke one client grant
  81. - `POST /admin/reconcile`: reconcile the search index with Git (`?mode=rebuild` for a full rebuild)
  82. - `POST /admin/memory/forget`: drop a bad `#lo-hi` summary (and ancestors) so it rebuilds from the raw log (`{"range":"0-1"}`)
  83. - `GET /admin/status`: inspect embedding & memory-summary health, rate-limit counters, pending compactions, and open alerts
  84. - `POST /admin/alerts/resolve`: clear open alerts (optional `?id=<n>` or `?source=embedding|memory-summary|dlq|reconcile`)
  85. ## Credits & License
  86. - Originally forked from [YudiG12/second-brain-mcp](https://github.com/YudiG12/second-brain-mcp) (MIT) and re-architected for self-hosted Node 24 + SQLite + Docker.
  87. - Episodic memory tree inspired by [VictorTaelin/OptMem](https://github.com/VictorTaelin/OptMem).
  88. - Licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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