diff --git a/CHANGELOG.md b/CHANGELOG.md index fa78792..65ca1d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,12 @@ # Changelog -All notable changes to tiroir are recorded here. Set the date on a release's -heading when tagging it. +All notable changes to Tiroir are recorded here. -## [Unreleased] + ## [0.1.0] - 2026-10-29 diff --git a/README.md b/README.md index a984d35..189c5fb 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,24 @@ -# tiroir +

+ Tiroir logo: a wooden chest of drawers +

+ +

Tiroir

+ +

+ Release + CI + Docs + License: Apache-2.0 + Python 3.13+ + Container image +

**Configurable, scoped memory for AI agents.** *Tiroir* is French for *drawer*. Give any AI agent a memory organised the way its user actually works. A developer thinks in repositories, an accountant in client files, a consultant in -engagements. With tiroir, the organisation of memory is configuration: you -declare your drawers, and tiroir handles storage, indexing, retrieval, context +engagements. With Tiroir, the organisation of memory is configuration: you +declare your drawers, and Tiroir handles storage, indexing, retrieval, context injection and sync. **Documentation: [ancelin-code.github.io/tiroir](https://ancelin-code.github.io/tiroir/)** @@ -28,7 +41,7 @@ injection and sync. - **You choose where your memory lives.** It syncs to a Git repository you pick, self-hosted or hosted. Nothing else leaves your machine: no telemetry, no third-party APIs, and embeddings are computed locally. -- **Git without Git.** tiroir syncs your memory across machines and team +- **Git without Git.** Tiroir syncs your memory across machines and team members through Git, and you never have to touch Git. - **Humans own the synthesis.** Logs are append-only, and summaries change only after you confirm. @@ -46,11 +59,11 @@ docker compose exec tiroir tiroir admin init Then follow the documentation: -- [Install tiroir on a VPS](https://ancelin-code.github.io/tiroir/install/vps/): +- [Installation Guide](https://ancelin-code.github.io/tiroir/install/vps/): the stack, the first administrator, a member and a store. - [Connect Claude Desktop](https://ancelin-code.github.io/tiroir/connect/claude-desktop/): add the server as a custom connector and sign in. -- [CLI reference](https://ancelin-code.github.io/tiroir/reference/cli/): the +- [CLI Reference](https://ancelin-code.github.io/tiroir/reference/cli/): the administration commands. ## Planned surfaces @@ -59,6 +72,8 @@ Then follow the documentation: - A guided setup skill that interviews you and designs your schema. - Presets beyond accounting firms, starting with developers. +The [Roadmap](https://ancelin-code.github.io/tiroir/roadmap/) says what each milestone brings. + ## Contributing `mise run check` runs every check, `mise run stack` builds the image from the @@ -77,3 +92,7 @@ documentation site. ## Licence [Apache-2.0](LICENSE). + +The documentation site sets its headings in [Daubenton](https://velvetyne.fr/fonts/daubenton/), +by Olivier Dolbeau ([Velvetyne](https://velvetyne.fr/)), under the SIL Open Font +License 1.1 (`docs/assets/fonts/OFL-Daubenton.txt`). diff --git a/delivery/contracts/cli.md b/delivery/contracts/cli.md index 4d30b7d..ab42d9b 100644 --- a/delivery/contracts/cli.md +++ b/delivery/contracts/cli.md @@ -51,9 +51,9 @@ members' next request (A4). | Command | Purpose | |---|---| -| `tiroir admin init` | First start: create the first administrator and print a one-time sign-in link (ADR-016). | +| `tiroir admin init` | First start: create the first administrator, handle `admin`, and print its initial password once, to change at the first sign-in (ADR-015). | | `tiroir admin members [list\|add --name [--admin]\|disable \|reset-password ]` | Members (A3). | -| `tiroir admin stores [list\|add --audience personal\|team --language [--owner ]]` | Stores. A `personal` store needs `--owner`. | +| `tiroir admin stores [list\|add --audience personal\|team --language [--owner ] [--preset ]]` | Stores. A `personal` store needs `--owner`. `--preset` names the preset the store starts from (S4, S7); the skeleton requires it (`preset.required`), and an unknown name is `preset.unknown`. | | `tiroir admin grant read\|write` / `tiroir admin revoke ` | Access (A2). | | `tiroir admin embedding [--model \| --external --external-model --key-env ]` | Embedding choice per store (R4). | | `tiroir admin mirrors [list\|add \|remove ]` | Mirrors (Y6); `add` over SSH prints the public key. | diff --git a/delivery/decisions/ADR-016-deployment.md b/delivery/decisions/ADR-016-deployment.md index e6b0674..9014081 100644 --- a/delivery/decisions/ADR-016-deployment.md +++ b/delivery/decisions/ADR-016-deployment.md @@ -2,6 +2,8 @@ **Status:** accepted **Date:** 2026-10-22 +**Amended:** 2026-11-04. `tiroir admin init` prints an initial password, as +ADR-015 decides, not a sign-in link; the skeleton was built that way. ## Context @@ -26,7 +28,8 @@ infrastructure, so they need the server reachable from the internet. administration page and kept in `server.db`. - **First start:** `docker compose up -d`, then `docker compose exec tiroir tiroir admin init`, which creates the first - administrator and prints a one-time sign-in link. The default model is + administrator, handle `admin`, and prints its initial password once, to change + at the first sign-in (ADR-015). The default model is downloaded in the background (ADR-006). - **Own machine:** the same stack. Two documented ways to get HTTPS (A5): - a tunnel (for example Cloudflare Tunnel or Tailscale Funnel) giving a diff --git a/delivery/tasks/docs-002.md b/delivery/tasks/docs-002.md new file mode 100644 index 0000000..18f4554 --- /dev/null +++ b/delivery/tasks/docs-002.md @@ -0,0 +1,73 @@ +--- +id: docs-002 +title: Polish the documentation site and document custom schemas for administrators +type: docs +epic: docs +depends_on: [] +parallel: true +conflicts_with: [] +tier: build +review: [] +--- + +## Context + +The review of the published site ([docs-001](docs-001.md)) found it very good +and asked for five changes: a dark mode, a logo, two clearer navigation labels, +and an administrator page on defining a custom schema. In 0.1.0 a store is +always created from a preset (`preset.required`), and the only way to give it a +custom schema is a preset directory of the administrator's own, found through +`TIROIR_PRESETS`. The guided init skill that would write a schema from an +interview (I1, I2) is planned for the `team` milestone and does not exist yet; +the page must say so and not promise it. Requirements: [the PRD](../prd.md); +schema format: [the schema contract](../contracts/schema.md). + +## Scope + +Files this task is expected to touch: + +- `zensical.toml` (colour palette with a light/dark toggle, the logo, the nav + labels, the new page in `nav` and in the `llmstxt` sections) +- `docs/assets/` (the logo, an SVG of an old-fashioned wooden chest of drawers, + usable on the light and dark palettes; also the favicon) +- `docs/install/custom-schema.md` (new: administrator guide to a custom schema) +- `docs/reference/cli.md`, `docs/install/vps.md`, `docs/index.md` (only the + links, and the sentences that say a store can only start from the bundled + preset) +- `delivery/tasks/docs-001.md` is left as it is: it records the first site. + +Out of scope: + +- Building the init skill, a `--schema` option or any code change. A mount for + custom presets in `compose.yaml` is documented as an override file the + administrator writes, not added to the shipped Compose file. +- A custom domain, a theme redesign beyond the palette and logo. + +## Acceptance criteria + +- The site offers a light and a dark mode, follows the visitor's system + preference by default, and has a visible toggle. +- The site shows a logo in the header and as favicon: a wooden chest of drawers, + legible on both modes. +- The navigation reads: Home; Server Installation (Installation Guide, + Custom Schema); Client Installation (Connect Claude Desktop, where other + hosts such as Claude Code will join later); CLI Reference. The page titles + match their navigation labels, Home excepted. +- `docs/install/custom-schema.md` walks an administrator, from a clean 0.1.0 + install, through: copying the bundled preset as a starting point, editing + `tiroir.yaml` (drawer types, fields, templates, sections, detection, + injection) with a pointer to the field reference, making the directory + available to the container and setting `TIROIR_PRESETS`, creating a store + with `--preset `, and checking the result. It states plainly that + there is no guided init in 0.1.0 and that it is planned. Every command and + path in it was run or read in the code, not guessed. +- No page says that `accounting-firm` is the only possible starting point + without pointing to the new page. +- `mise run docs:build` succeeds with no warning, and `llms.txt` lists the new + page. + +## Validation + +`mise run docs:build`, then open the built site (`mise run docs:serve`) in both +modes. Follow the new page's steps against a local store and confirm the store +is created from the custom preset. diff --git a/docs/assets/extra.css b/docs/assets/extra.css new file mode 100644 index 0000000..b9ebbb8 --- /dev/null +++ b/docs/assets/extra.css @@ -0,0 +1,164 @@ +/* Keep the first column of a table, the term, the code or the message, on one + line: only the explanation next to it wraps. */ +.md-typeset table:not([class]) td:first-child, +.md-typeset table:not([class]) th:first-child { + white-space: nowrap; +} + +/* Align the first line of every cell on a baseline, so that a cell starting + with code does not look lower than its neighbours. */ +.md-typeset table:not([class]) td { + vertical-align: baseline; +} + +/* Status of a milestone on the roadmap. */ +.status { + display: inline-block; + padding: 0.05em 0.7em; + border-radius: 1em; + font-size: 0.8em; + font-weight: 700; + white-space: nowrap; + border: 1px solid currentcolor; +} +.status-done { color: #2e7d32; background: rgb(46 125 50 / 12%); } +.status-next { color: #b26a00; background: rgb(255 160 0 / 15%); } +.status-planned { color: #607d8b; background: rgb(96 125 139 / 12%); } +.status-goal { color: #6a1b9a; background: rgb(106 27 154 / 10%); } +[data-md-color-scheme="slate"] .status-done { color: #81c784; } +[data-md-color-scheme="slate"] .status-next { color: #ffb74d; } +[data-md-color-scheme="slate"] .status-planned { color: #b0bec5; } +[data-md-color-scheme="slate"] .status-goal { color: #ce93d8; } + +/* Daubenton, by Olivier Dolbeau (Velvetyne, SIL OFL): a serif revived from the + letters engraved on the Grande Galerie de l'Evolution in Paris. One weight, + used for the site name and the headings. The licence is next to the file. */ +@font-face { + font-family: Daubenton; + src: url("fonts/Daubenton.woff2") format("woff2"); + font-weight: 400; + font-style: normal; + font-display: swap; +} +.md-header__topic:first-child .md-ellipsis, +.md-typeset h1, +.md-typeset h2 { + font-family: Daubenton, Georgia, serif; + font-weight: 400; + font-synthesis: none; +} +.md-header__topic:first-child .md-ellipsis { + font-size: 1.15em; + letter-spacing: 0.02em; +} + +/* The path to 1.0.0 on the roadmap: a line of steps, vertical on a phone. */ +.path { + --path-done: #2e7d32; + --path-next: #b26a00; + --path-planned: #90a4ae; + --path-goal: #6a1b9a; +} +[data-md-color-scheme="slate"] .path { + --path-done: #81c784; + --path-next: #ffb74d; + --path-planned: #78909c; + --path-goal: #ce93d8; +} +[dir] .md-typeset ol.path { + display: flex; + margin: 2.5rem 0 2rem; + padding: 0; + list-style: none; +} +/* Material gives every list item a left margin, with a selector that is + hard to outrank: without this the steps are pushed to the right. */ +.md-typeset ol.path > .path__step { + position: relative; + flex: 1; + margin: 0; + padding-top: 2.6rem; + text-align: center; +} +.md-typeset .path__step a { + display: block; + padding: 0 0.3rem; + color: inherit; + text-decoration: none; +} +.path__step::before { + content: ""; + position: absolute; + top: 0.9rem; + right: 50%; + width: 100%; + border-top: 3px solid var(--path-done); +} +.path__step:first-child::before { display: none; } +.path__step--planned::before, +.path__step--goal::before { + border-top: 3px dashed var(--path-planned); +} +.path__node { + position: absolute; + top: 0.2rem; + left: 50%; + display: flex; + align-items: center; + justify-content: center; + width: 1.4rem; + height: 1.4rem; + margin-left: -0.7rem; + border: 3px solid var(--path-planned); + border-radius: 50%; + background: var(--md-default-bg-color); +} +.path__step--done .path__node { border-color: var(--path-done); background: var(--path-done); } +.path__step--next .path__node { border-color: var(--path-next); } +.path__step--goal .path__node { + top: -0.3rem; + width: 2.4rem; + height: 2.4rem; + margin-left: -1.2rem; + border-color: var(--path-goal); +} +.path__node img { width: 1.5rem; height: 1.5rem; } +.path__name { display: block; font-weight: 700; } +.path__what { display: block; min-height: 2.6em; font-size: 0.8em; line-height: 1.3; opacity: 0.85; } +.path__state { + display: block; + margin-top: 0.15rem; + font-size: 0.7em; + font-weight: 700; + letter-spacing: 0.04em; + text-transform: uppercase; +} +.path__step--done .path__state { color: var(--path-done); } +.path__step--next .path__state { color: var(--path-next); } +.path__step--planned .path__state { color: var(--path-planned); } +.path__step--goal .path__state { color: var(--path-goal); } +@media (prefers-reduced-motion: no-preference) { + .path__step--next .path__node { animation: path-pulse 2s ease-out infinite; } +} +@keyframes path-pulse { + 0% { box-shadow: 0 0 0 0 rgb(255 160 0 / 55%); } + 100% { box-shadow: 0 0 0 0.7rem rgb(255 160 0 / 0%); } +} +@media (max-width: 44.9375em) { + [dir] .md-typeset ol.path { flex-direction: column; margin-left: 0.5rem; } + .md-typeset ol.path > .path__step { padding: 0 0 1.6rem 2.6rem; text-align: left; } + .path__what { min-height: 0; } + .path__step::before { + top: -1.6rem; + right: auto; + left: 0.7rem; + width: 0; + height: 1.9rem; + border-top: 0; + border-left: 3px solid var(--path-done); + } + .path__step--planned::before, + .path__step--goal::before { border-top: 0; border-left: 3px dashed var(--path-planned); } + .path__node { top: 0.1rem; left: 0; margin-left: 0; } + .path__step--goal .path__node { top: -0.4rem; left: -0.5rem; margin-left: 0; } +} diff --git a/docs/assets/fonts/Daubenton.woff2 b/docs/assets/fonts/Daubenton.woff2 new file mode 100644 index 0000000..b3ba821 Binary files /dev/null and b/docs/assets/fonts/Daubenton.woff2 differ diff --git a/docs/assets/fonts/OFL-Daubenton.txt b/docs/assets/fonts/OFL-Daubenton.txt new file mode 100644 index 0000000..fd9b59c --- /dev/null +++ b/docs/assets/fonts/OFL-Daubenton.txt @@ -0,0 +1,103 @@ +This Font Software is licensed under the SIL Open Font License, Version 1.1. +This license is copied below, and is also available with a FAQ at: +http://scripts.sil.org/OFL + +SIL Open Font License v1.1 +==================================================== + + +Preamble +---------- + +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + + +Definitions +------------- + +`"Font Software"` refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +`"Reserved Font Name"` refers to any names specified as such after the +copyright statement(s). + +`"Original Version"` refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +`"Modified Version"` refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +`"Author"` refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + + +Permission & Conditions +------------------------ + +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1. Neither the Font Software nor any of its individual components, + in Original or Modified Versions, may be sold by itself. + +2. Original or Modified Versions of the Font Software may be bundled, + redistributed and/or sold with any software, provided that each copy + contains the above copyright notice and this license. These can be + included either as stand-alone text files, human-readable headers or + in the appropriate machine-readable metadata fields within text or + binary files as long as those fields can be easily viewed by the user. + +3. No Modified Version of the Font Software may use the Reserved Font + Name(s) unless explicit written permission is granted by the corresponding + Copyright Holder. This restriction only applies to the primary font name as + presented to the users. + +4. The name(s) of the Copyright Holder(s) or the Author(s) of the Font + Software shall not be used to promote, endorse or advertise any + Modified Version, except to acknowledge the contribution(s) of the + Copyright Holder(s) and the Author(s) or with their explicit written + permission. + +5. The Font Software, modified or unmodified, in part or in whole, + must be distributed entirely under this license, and must not be + distributed under any other license. The requirement for fonts to + remain under this license does not apply to any document created + using the Font Software. + + +Termination +----------- + +This license becomes null and void if any of the above conditions are +not met. + + + DISCLAIMER + + THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT + OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE + COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL + DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM + OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg new file mode 100644 index 0000000..66b9de9 --- /dev/null +++ b/docs/assets/logo.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/docs/changelog.md b/docs/changelog.md new file mode 120000 index 0000000..04c99a5 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1 @@ +../CHANGELOG.md \ No newline at end of file diff --git a/docs/connect/claude-desktop.md b/docs/connect/claude-desktop.md index dce7cb2..426d101 100644 --- a/docs/connect/claude-desktop.md +++ b/docs/connect/claude-desktop.md @@ -1,6 +1,6 @@ # Connect Claude Desktop -A member adds tiroir to Claude Desktop as a custom connector, signs in once, +A member adds Tiroir to Claude Desktop as a custom connector, signs in once, and then asks Claude to search and write their memory. Nothing is installed on the member's machine. This page covers Claude Desktop only; the web and mobile apps and the Claude Code plugin come later. @@ -8,7 +8,7 @@ apps and the Claude Code plugin come later. You need: - the server's address, `https://`, from the administrator who - followed [Install tiroir on a VPS](../install/vps.md); + followed [Installation Guide](../install/vps.md); - your handle and the initial password the administrator gave you; - a Claude plan that allows custom connectors. @@ -22,13 +22,13 @@ You need: |---|---| | Name | `tiroir`, or any name you like. | | Remote MCP server URL | The server's address followed by `/mcp`, for example `https://memoire.example.org/mcp`. | - | OAuth Client ID, OAuth Client Secret (under **Advanced settings**, if shown) | Leave both empty. tiroir registers the application by itself. | + | OAuth Client ID, OAuth Client Secret (under **Advanced settings**, if shown) | Leave both empty. Tiroir registers the application by itself. | 4. Confirm with **Add**. ## 2. Sign in -Choosing **Connect** on the new connector opens your browser on the tiroir +Choosing **Connect** on the new connector opens your browser on the Tiroir server. Two pages follow, both plain and titled "tiroir": 1. **Sign in**: a form with *Handle* and *Password*. Enter your handle and the @@ -49,10 +49,10 @@ administrator disables your account. Start a new conversation, enable the connector's tools if Claude asks, and ask: -> Search my tiroir memory for "échéance TVA". +> Search my Tiroir memory for "échéance TVA". Claude calls `tiroir_search` and shows the hits, each naming its store, -drawer, and date. If nothing matches, tiroir says so explicitly instead of +drawer, and date. If nothing matches, Tiroir says so explicitly instead of returning loose results. ## 4. A first log entry diff --git a/docs/index.md b/docs/index.md index e3eaf95..8d850de 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,16 +1,16 @@ -# tiroir +# Tiroir **Configurable, scoped memory for AI agents.** *Tiroir* is French for *drawer*. -tiroir gives AI agents a memory organised the way their users actually work. A +Tiroir gives AI agents a memory organised the way their users actually work. A developer thinks in repositories, an accountant in client files, a consultant -in engagements. With tiroir, that organisation is configuration: a store holds -drawers, and tiroir handles storage, indexing and retrieval. Memory is plain +in engagements. With Tiroir, that organisation is configuration: a store holds +drawers, and Tiroir handles storage, indexing and retrieval. Memory is plain Markdown in a Git repository on your own server; nothing leaves it. ## Who it is for -- **Administrators** who run one tiroir server for themselves or their team, on +- **Administrators** who run one Tiroir server for themselves or their team, on a VPS with Docker Compose. - **Members** of that team who connect Claude Desktop to the server, then ask Claude to search their memory and to log what happened. @@ -21,20 +21,23 @@ Markdown in a Git repository on your own server; nothing leaves it. certificate by itself. The image is published for `amd64` and `arm64`. - Members, personal and team stores, and read or write access, managed with the [administration CLI](reference/cli.md) inside the container. -- A store starts from a preset. The one bundled preset, `accounting-firm`, - comes with invented client drawers to try the server on. +- A store starts from a preset. The bundled preset, `accounting-firm`, comes + with invented client drawers to try the server on; you can write a + [custom schema](install/custom-schema.md) as a preset of your own. - Claude Desktop connects as a custom connector, signs in with OAuth, and gets four tools: search, read, log, and the list of the stores the member can reach. ## Where to start -1. [Install tiroir on a VPS](install/vps.md): the stack, the first +1. [Installation Guide](install/vps.md): the stack, the first administrator, a member and a store. 2. [Connect Claude Desktop](connect/claude-desktop.md): add the server as a custom connector and sign in. -3. [CLI reference](reference/cli.md): every administration command, with its +3. [Custom Schema](install/custom-schema.md): organise a store's memory your + own way. +4. [CLI Reference](reference/cli.md): every administration command, with its arguments and an example. -tiroir is open source under the Apache-2.0 licence; its code is on +Tiroir is open source under the Apache-2.0 licence; its code is on [GitHub](https://github.com/ancelin-code/tiroir). diff --git a/docs/install/custom-schema.md b/docs/install/custom-schema.md new file mode 100644 index 0000000..a23c1cd --- /dev/null +++ b/docs/install/custom-schema.md @@ -0,0 +1,435 @@ +# Custom Schema + +By default, a Tiroir store is organised like the bundled `accounting-firm` +example: one drawer per client. If your team works differently, you describe +your own organisation in a file, the **schema**, and Tiroir does the rest. This +page takes you from nothing to a working store with your own drawers. Count +about 30 minutes for a first try. + +!!! warning "No guided setup in 0.1.0" + + You write the schema by hand, on the server. A guided *init*, where Claude + interviews a member in their language and proposes the schema, is planned + (see the [Roadmap](../roadmap.md#3-team)) and does not exist yet. Until then, a custom schema + is a **preset** of your own: a folder on the server that a store is + created from. + +## The ideas in five minutes + +Tiroir organises memory the way people organise paper files, and keeps it as +plain Markdown files in a Git repository. + +| Term | What it is | Example | +|---|---|---| +| **Store** | One memory, one Git repository. A store is either **personal**, owned by one member, or **team**, shared by the members you grant. | `my-team-memory` | +| **Drawer** | One "thing" your memory is about: one client, one code repository, one engagement. A drawer is a folder. | the drawer of the `billing-api` repository | +| **Drawer type** | The kind of a drawer. All the drawers of a type are organised the same way. | `repo`, `client` | +| **Summary** | The drawer's current state: a short document of named sections, rewritten as things change. | what `billing-api` is for, its architecture | +| **Log** | The drawer's history: one small dated file per event, never edited afterwards. | "2026-10-21: migrated invoices to the new table" | +| **Shared space** | Documents that belong to no drawer: conventions, procedures, calendars. | `shared/conventions.md` | +| **Schema** | The file `tiroir.yaml` that declares the drawer types and how each one is organised. | this page | +| **Preset** | A folder holding a schema, its templates, shared documents and, optionally, starting drawers. | `my-team` | + +A store with one drawer looks like this on disk: + +```text +my-team-memory/ + tiroir.yaml the schema + MEMORY.md the table of contents, generated by tiroir (see step 5) + templates/ what a new summary or log entry looks like + shared/conventions.md a shared document + repos/billing-api/ one drawer + summary.md its summary + log/2026/10/…md its log, one file per entry +``` + +## Before you write anything: three questions + +Take a sheet of paper and answer: + +1. **What are your drawers?** The things your team keeps coming back to: + clients, repositories, projects, patients, suppliers. Start with one type. +2. **What do you want to remember about each one?** List the headings of the + summary, in the order you would read them. Four to six is plenty. These + become the summary *sections*. +3. **What identifies a drawer?** A code, a name, a slug. This becomes the + drawer's *fields*, and its folder name. + +!!! tip "Two rules of thumb" + + - **What is true now goes in the summary; what happened goes in the log.** + "The service runs on PostgreSQL" is a summary fact. "We moved to + PostgreSQL on 21 October" is a log entry. + - **A drawer is something people name in conversation.** If your team says + "have you seen the Dupont file?" or "what about billing-api?", then + clients or repositories are your drawers. + +The rest of the page builds a store for a team that wants one drawer per code +repository. Replace "repository" with your own answer as you go. + +## Step 1: Prepare the presets folder + +The `presets/` folder of the repository you cloned in the +[Installation Guide](vps.md#1-get-the-stack) holds the bundled presets, the same +ones as the image. You will add yours next to them. From the directory that +holds `compose.yaml`: + +```sh +mkdir -p presets/my-team/templates presets/my-team/shared +``` + +`presets/accounting-firm` is a complete example of every file below, so keep it +open as you read. `my-team` is the name you will give to `--preset`: lowercase +letters, digits and hyphens, starting with a letter or a digit. + +The server reads its presets from inside the container, so tell Compose to use +this folder instead of the one in the image. Create `compose.override.yaml` +next to `compose.yaml`; Compose reads it automatically: + +```yaml +services: + tiroir: + volumes: + - ./presets:/app/presets:ro +``` + +```sh +docker compose up -d +``` + +From now on, a change to a file under `presets/` is seen by the server at once; +no restart is needed. + +## Step 2: Write the schema + +Create `presets/my-team/tiroir.yaml`: + +```yaml +# Version of the file format. Always 1. +tiroir: 1 + +# The identity of the store. You do not choose it here: `stores add` replaces +# id, name, audience and language with what you type on the command line. +# Only `description` is kept. The other values just have to be valid. +store: + id: 00000000-0000-0000-0000-000000000000 + name: placeholder + audience: team + language: en + description: "What our team knows about its repositories." + +# The shared space: documents that belong to no drawer. +shared: + topics: [conventions, release process] + +# The kinds of drawer. One entry per kind; the key is the type's name. +drawer_types: + repo: + label: Repository + label_plural: Repositories + description: "One code repository of the team." + # Where a drawer lives. {name} is replaced by the drawer's `name` field. + path: "repos/{name}" + # The drawer's identity card: facts that are not prose. + fields: + name: + type: text + required: true + pattern: "[a-z0-9-]+" + description: "The repository's name, in lowercase, such as billing-api." + aliases: + type: list + description: "Other names people use for it." + language: + type: enum + values: [python, typescript, go, other] + description: "The main language." + # The summary: a template, and the headings it is made of, in order. + summary: + template: templates/repo-summary.md + sections: [Purpose, Architecture, Conventions, Open questions] + # What a new log entry looks like. + log: + template: templates/repo-log.md + # Optional: how a drawer is recognised in a conversation, and what is + # put before Claude when it comes up. + detect: + names: [name, aliases] + inject: + sections: [Purpose, Conventions] + max_tokens: 800 +``` + +Read it from the top: + +- **`tiroir: 1`** is the version of the file format. Always `1`. +- **`store`** is a placeholder. When you create a store, Tiroir generates its + `id` and takes `name`, `audience` and `language` from the command line, so + what you write there is replaced. Keep the block, with valid values, and + write a `description`: it is the one line kept in the store. +- **`shared.topics`** says what the shared space is about. It is a hint for + Claude, not a list of files. +- **`drawer_types`** is the heart of the file: one entry per kind of drawer, + here `repo`. The key (`repo`) is the type's name. + - **`label`, `label_plural`, `description`** are the words used when Tiroir + talks about the type. Write them in the store's language. + - **`path`** says where a drawer lives. `repos/{name}` means that the + drawer of a repository whose `name` is `billing-api` is the folder + `repos/billing-api`. The placeholder must be a **required** field, and it + is what makes each drawer unique. + - **`fields`** is the drawer's identity card, the information that is not + prose. Each field has a `type`: `text`, `number`, `date` (`2026-10-21`), + `boolean`, `enum` (one of the `values` you list) or `list` (a list of + text). `required: true` makes it mandatory, and `pattern` restricts a + `text` field to a regular expression. + - **`summary`** names the template of a new summary and its **sections**, + the level-2 headings, in order. They are the units that Tiroir finds, + reads and, later, merges. + - **`log`** names the template of a new log entry. Optional. + - **`detect.names`** lists the fields whose values designate the drawer in a + conversation. Optional. Most of what uses it arrives with the next + release (see the [Roadmap](../roadmap.md#2-retrieval)), so in 0.1.0 you can leave it out or fill it in now. + - **`inject.sections`** and **`max_tokens`** say which sections are put + before Claude when the drawer comes up, and how much. Optional, with the + same remark. + +Then the two templates. A summary template holds exactly the sections you +declared, in the same order, with a line of guidance under each. Create +`presets/my-team/templates/repo-summary.md`: + +```markdown +# {name} + +## Purpose + +What this repository does, and for whom. + +## Architecture + +The main parts and how they fit together. + +## Conventions + +What to know before changing the code. + +## Open questions + +What is still undecided. +``` + +`{name}` is replaced by the drawer's field of that name when it is created. The +log template is the shape of a new entry. Create +`presets/my-team/templates/repo-log.md`: + +```markdown +**What happened:** one sentence. + +**Next step:** who does what, and by when. +``` + +Finally a shared document, `presets/my-team/shared/conventions.md`. Claude reads +it the first time it uses the store in a session, so put in it what you want +every entry to respect: + +```markdown +--- +title: Team conventions +--- +# Team conventions + +## Writing + +Write in English, in short sentences. + +## Secrets + +Never write a password or a token in memory. +``` + +## Step 3: Give it a first drawer + +!!! warning "An important limitation of 0.1.0" + + A member cannot create a drawer from Claude: Claude can search, read and + add log entries, nothing more. **Every drawer you want must therefore exist + when the store is created**, and there is no way to add one afterwards. + This will be lifted: creating drawers from Claude is planned (see the + [Roadmap](../roadmap.md#3-team)). Until then, plan your first drawers + carefully. + +You give the store its drawers in a `data/` folder of the preset, laid out +exactly as in the store, one folder per drawer. + +The same limit applies to what is written in a drawer. **You write the summary**, +here, in the preset, and nothing completes it later: in 0.1.0, neither Claude +nor a member can change a summary, so write what you know, as completely as you +can. Claude reads it to know the drawer. **The log, by contrast, grows**: +members ask Claude to add entries, each one a new dated file. Both are searched. +Updating summaries from Claude is planned too, and a person will confirm each +update (see the [Roadmap](../roadmap.md#3-team)). + +Create the first drawer's summary, +`presets/my-team/data/repos/billing-api/summary.md`: + +```markdown +--- +type: repo +name: billing-api +aliases: [billing, invoices-api] +language: python +--- +# billing-api + +## Purpose + +Issues invoices and records payments for the web shop. + +## Architecture + +A FastAPI service in front of a PostgreSQL database. + +## Conventions + +Every change needs a migration and a test. + +## Open questions + +Do we keep the legacy CSV export? +``` + +The top block, between the two `---` lines, holds the drawer's fields: `type` is +the name of the drawer type, and the others are the fields you declared. Then +come the sections, with exactly the headings of the schema. Add one folder like +this per drawer. + +!!! warning "Keep to the schema" + + In 0.1.0, Tiroir checks `tiroir.yaml` when it creates a store, but it does + not check the drawers of `data/`: a misspelled section or a value that is + not in an `enum` goes through. Copy the template headings exactly. + +## Step 4: Create the store + +Try it on a machine that does not matter first, for example your laptop with the +same `compose.yaml`: 0.1.0 has no command to delete a store, so a store you +created by mistake stays there. + +```sh +docker compose exec tiroir tiroir admin stores add my-team-memory \ + --audience team --language en --preset my-team +``` + +The command prints `store: my-team-memory`. A team store has no member yet: give +access to the members you created (see the +[Installation Guide](../install/vps.md#5-create-a-member)). + +```sh +docker compose exec tiroir tiroir admin grant alice my-team-memory write +docker compose exec tiroir tiroir admin grant bob my-team-memory read +docker compose exec tiroir tiroir admin stores list +``` + +If the schema is wrong, nothing is created, and every problem is listed with its +location: + +```text +error: schema.invalid: the schema has 1 violation: +schema.invalid: drawer_types.repo.fields.language.type (line 35): expected one of: text, number, date, boolean, enum, list +``` + +The key path (`drawer_types.repo.fields.language.type`) and the line say where +to look. Fix the file and run the command again. + +| Message | Meaning | +|---|---| +| `schema.invalid` | A key is unknown, misspelled, mis-indented or of the wrong type. An unknown key is always an error, so that a typo never silently disables a rule. | +| `schema.invalid-path` | A drawer type's `path` has no placeholder of a required field. | +| `schema.unknown-section` | `inject.sections` or a template names a heading that is not in `summary.sections`. | +| `preset.unknown` | There is no folder of that name in `presets/`, or the name has capitals or spaces. | +| `store.exists` | A store with that name exists already. | + +## Step 5: Look at the result + +The store is a Git repository inside the container, in a folder named by an id, +not by the store's name. Find yours by its title: + +```sh +docker compose exec tiroir sh -c ' + for repo in /data/stores/*.git; do + echo "$repo: $(git --git-dir="$repo" show main:MEMORY.md | head -1)" + done' +``` + +```text +/data/stores/6f0c5a3e-….git: # my-team-memory +``` + +Then print the table of contents that Tiroir generated, `MEMORY.md`, and the +list of files, with the folder you found: + +```sh +docker compose exec tiroir git --git-dir=/data/stores/.git show main:MEMORY.md +docker compose exec tiroir git --git-dir=/data/stores/.git ls-tree -r --name-only main +``` + +`MEMORY.md` looks like this: + +```text +# my-team-memory + +What our team knows about its repositories. + +Each drawer is a folder holding `summary.md`, its summary, and `log/`, its dated log entries. Shared documents are under `shared/`. + +## Repositories + +- [[repos/billing-api/summary]] — Repository: billing-api, billing, invoices-api +``` + +!!! info "What is `MEMORY.md`?" + + It is the store's table of contents: its name, a short explanation of the + layout, and one line per drawer. Tiroir generates it from the drawers, so + you never write it, and a hand edit would be overwritten. It exists so that + a person can open the store without Tiroir, in a text editor or as an + Obsidian vault, and find their way around. + +Then connect as `alice` with [Claude Desktop](../connect/claude-desktop.md) and +try, in that order: + +> Which drawers do I have in my-team-memory? +> +> Show me the summary of billing-api. +> +> Add a log entry to billing-api: "Moved the invoice export to a nightly job." + +Claude should list the drawer, read its summary and writes the entry as a new dated +file under `repos/billing-api/log/`. If all three work, your schema works. + +## Going further + +- **A second drawer type.** Add another entry under `drawer_types` (`project`, + `incident`), with its own `path`, fields, templates and sections. Two types + must not use overlapping paths: `repos/{name}` and `repos/{name}/docs` would + clash. +- **A different language.** `language` is the memory language, for example `fr`. + Write the labels, the section headings and the templates in that language; + `--language` on `stores add` overrides the one in the file. +- **Learn from a complete example.** `presets/accounting-firm` is the full + version of what you built: a French schema with six fields, six sections, + templates, shared procedures and 23 drawers with their logs. +- **Every key, every rule.** The [Schema Reference](../reference/schema.md) + lists them all, with the error each one gives. + +## Good to know + +- **A preset is a starting point.** It is copied when the store is created. + Changing the preset afterwards does not change the stores already made from + it, and 0.1.0 has no command to change the schema of an existing store; schema + (see the [Roadmap](../roadmap.md#4-operations)). Settle the schema on a test store before the real one. +- **Upgrades.** With `./presets` mounted, the server reads the presets of your + clone, not those of the image. A `git pull` brings the new bundled presets + and leaves yours alone. + +See the [CLI Reference](../reference/cli.md) for `stores add` and `grant`, and +the [Installation Guide](../install/vps.md) for the stack. diff --git a/docs/install/vps.md b/docs/install/vps.md index 0e83275..4c4f383 100644 --- a/docs/install/vps.md +++ b/docs/install/vps.md @@ -1,8 +1,8 @@ -# Install tiroir on a VPS +# Installation Guide This guide takes an administrator from an empty Linux server to a running -tiroir server with a first member and a first store. It covers the skeleton -milestone: one server, one stack, started with Docker Compose behind Caddy, +Tiroir server with a first member and a first store. It covers what 0.1.0 does: +one server, one stack, started with Docker Compose behind Caddy, which obtains the HTTPS certificate by itself. To connect Claude Desktop afterwards, follow [Connect Claude Desktop](../connect/claude-desktop.md). @@ -17,13 +17,13 @@ afterwards, follow [Connect Claude Desktop](../connect/claude-desktop.md). - A shell on the VPS, and an e-mail address for the certificate authority's expiry notices. -tiroir keeps all its state in one Docker volume, `tiroir-data`. It needs no +Tiroir keeps all its state in one Docker volume, `tiroir-data`. It needs no database server and sends no e-mail. ## 1. Get the stack The stack is three files: `compose.yaml`, `deploy/Caddyfile` and `.env`. The -tiroir image itself is published at `ghcr.io/ancelin-code/tiroir`, for `amd64` +Tiroir image itself is published at `ghcr.io/ancelin-code/tiroir`, for `amd64` and `arm64`, so nothing is built on the VPS. Clone the repository on the VPS to get the three files: @@ -54,7 +54,7 @@ docker compose pull docker compose up -d ``` -Compose pulls the tiroir image for the tag in `.env` and the Caddy image, then +Compose pulls the Tiroir image for the tag in `.env` and the Caddy image, then starts both. Check that they run and that the server answers through Caddy: ```sh @@ -81,8 +81,8 @@ docker compose exec tiroir tiroir admin init The command creates the administrator, handle `admin`, and prints an initial password once. Copy it now; it cannot be shown again. At the first sign-in, -tiroir asks for a new password of at least 12 characters. Choose a strong one: -tiroir has no second factor in this version, so limit who can reach the server +Tiroir asks for a new password of at least 12 characters. Choose a strong one: +Tiroir has no second factor in this version, so limit who can reach the server if you can. `tiroir admin init` refuses to run twice (`the server already has an @@ -110,7 +110,8 @@ docker compose exec tiroir tiroir admin stores list `--preset accounting-firm` fills the store with the bundled synthetic dataset: 23 invented client drawers, each with a summary and a log. The owner gets access to the store. The command prints `store: alice-memory`, and the list -shows `alice-memory personal fr 1 members`. +shows `alice-memory personal fr 1 members`. To organise a store's memory +your own way, see [Custom Schema](custom-schema.md). The store is a bare Git repository, `/data/stores/.git` in the container, named by an id rather than by the store's name: diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 7b7dc0d..1e5b2e9 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1,6 +1,6 @@ -# CLI reference +# CLI Reference -tiroir is administered with one command, `tiroir`, that ships inside the +Tiroir is administered with one command, `tiroir`, that ships inside the server's image. In version 0.1.0 it holds the **administration CLI**, `tiroir admin`, which you run in the server's container from the directory of the stack: @@ -21,8 +21,8 @@ below leave out the `docker compose exec tiroir` prefix. A member CLI, run on a member's own machine against the server (search, read, log, proposals), and the administration commands for embeddings, mirrors, evaluation, backups and the server's state are planned for later - releases. They are not in 0.1.0, and this page will document them when they - are. + releases (see the [Roadmap](../roadmap.md)). They are not in 0.1.0, and this + page will document them when they are. ## `tiroir` @@ -168,7 +168,7 @@ usage: tiroir admin stores add [-h] --audience {personal,team} | `--audience {personal,team}` | `personal`: one member's memory. `team`: shared by the members you grant. Required. | | `--language LANGUAGE` | The language of the store's content, such as `fr` or `en`. Required. | | `--owner OWNER` | The handle of the member who owns the store. They get write access, and the store becomes their default. Required for a `personal` store. | -| `--preset PRESET` | The preset the store starts from. In 0.1.0, every store starts from a preset, and the only one is `accounting-firm`, filled with invented client drawers. | +| `--preset PRESET` | The preset the store starts from. In 0.1.0, every store starts from a preset: the bundled `accounting-firm`, filled with invented client drawers, or one of your own ([Custom Schema](../install/custom-schema.md)). | Creates the store and indexes it. diff --git a/docs/reference/schema.md b/docs/reference/schema.md new file mode 100644 index 0000000..de4ad3e --- /dev/null +++ b/docs/reference/schema.md @@ -0,0 +1,102 @@ +# Schema Reference + +The schema is the file `tiroir.yaml` at the root of a store. It declares the +store's identity and every drawer type. This page lists every key. To build one +step by step, follow [Custom Schema](../install/custom-schema.md). + +The file is YAML, UTF-8, one document. Anchors, aliases, tags and several +documents are refused. **An unknown key is an error**, so that a typo or a +wrong indentation never silently disables a rule. Paths are relative to the +store's root and use `/`. + +## Top level + +| Key | Type | Required | Meaning | +|---|---|---|---| +| `tiroir` | integer | yes | The version of the file format. `1`. | +| `store.id` | UUID | yes | The store's identity, generated by `stores add`. Never changes. | +| `store.name` | slug | yes | The short name shown in results, such as `acme`. | +| `store.audience` | `personal` or `team` | yes | Who reads the store. | +| `store.language` | language code | yes | The memory language, such as `en` or `fr`. | +| `store.description` | text | no | One line on what the store holds. | +| `shared.path` | path | no | The folder of the shared space. Default `shared`. | +| `shared.topics` | list of text | no | What the shared space is about. | +| `shared.conventions` | path | no | The shared document Claude reads first. Default `shared/conventions.md` when it exists. | +| `context.conventions_max_tokens` | integer | no | A cap on the size of that document. Default 1500. | +| `drawer_types` | mapping | yes | The drawer types, at least one, each under `drawer_types.`. | + +In a preset, the `store` block is a placeholder: `stores add` generates the +`id` and replaces `name`, `audience` and `language` with its own arguments. Only +`description` is kept, and the other values have to be valid. + +## Drawer type + +A type name is a slug, such as `client` or `repo`. + +| Key | Type | Required | Meaning | +|---|---|---|---| +| `label` | text | yes | The human name of the type, in the memory language. | +| `label_plural` | text | no | Its plural. | +| `description` | text | no | What a drawer of this type holds. | +| `path` | pattern | yes | The folder of each drawer, such as `clients/{code}`. See below. | +| `fields` | mapping | yes | The drawer's metadata, one entry per [field](#field). | +| `summary.template` | path | yes | The Markdown template of a new summary. See [Templates](#templates). | +| `summary.sections` | list of text | yes | The level-2 headings of the summary, in order, at least one. | +| `log.template` | path | no | The template of a new log entry. Default: empty. | +| `detect.names` | list of field names | no | The fields whose values designate a drawer in a conversation. They must be `text` or `list` fields. | +| `detect.cwd` | field name | no | The field compared with the folders of the working directory, for tools that send one. | +| `inject.sections` | list of text | no | The sections put before Claude when the drawer comes up. Default: all. Each must be in `summary.sections`. | +| `inject.max_tokens` | integer | no | A cap on one drawer's injected block. Default 800. | + +Most of what `detect` and `inject` drive arrives with the next release (see the [Roadmap](../roadmap.md#2-retrieval)). +They are checked today, and you can declare them now. + +### The `path` pattern + +`{field}` is replaced by the **slug** of that field's value: lowercase, accents +removed, every run of other characters replaced by `-`. A client named +`Boulangerie Dupont & Fils` with the pattern `clients/{name}` lives in +`clients/boulangerie-dupont-fils`. A pattern must contain at least one +placeholder of a **required** field, and the patterns of two types must not +overlap. + +## Field + +A field's name is a slug. `type`, `author` and `date` are reserved. + +| Key | Type | Required | Meaning | +|---|---|---|---| +| `type` | see below | yes | `text`, `number`, `date`, `boolean`, `enum` or `list`. | +| `required` | boolean | no | Default `false`. | +| `values` | list of text | for `enum` | The allowed values. | +| `pattern` | regular expression | no | For `text` only. The whole value must match. | +| `default` | a value of the field's type | no | Used when a drawer is created without the field. | +| `description` | text | no | Shown in validation messages. | + +A `date` is written `YYYY-MM-DD`. A `list` is a list of text. Computed fields do +not exist. + +## Templates + +A summary template is a Markdown file that holds **exactly** the headings of +`summary.sections`, in the same order, with an optional line of guidance under +each. It can use `{field}` placeholders, replaced when a drawer is created. The +drawer's metadata, between two `---` lines at the top of `summary.md`, is +generated from the fields and is not part of the template. + +## Errors + +When Tiroir creates a store, it checks `tiroir.yaml` and reports **every** +violation, each with its key path and its line. + +| Code | When | +|---|---| +| `schema.invalid` | A key is unknown, a type is wrong, a required key is missing, or the YAML is malformed. | +| `schema.unsupported-version` | `tiroir` is greater than the version this server reads. | +| `schema.invalid-path` | A `path` has no placeholder of a required field, or overlaps another type's. | +| `schema.unknown-section` | `inject.sections` or a template heading is not in `summary.sections`. | +| `schema.invalid-detect` | A field listed in `detect` is neither `text` nor `list`. | + +Nothing is created when there is a violation. In 0.1.0, the drawers of a +preset's `data/` folder are not checked against the schema: copy the template +headings exactly. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..1e6b93c --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,203 @@ +# Roadmap + +Tiroir is delivered in **milestones**: four slices of the product, each working +from end to end on a real server. A milestone ends with a check on a running +server and a review of what it taught, and only then is the next one cut. This +page says where Tiroir stands, what each milestone brings, and what 0.1.0 cannot +do yet. + +No dates are promised. A milestone ships when its check holds, and the +[Changelog](changelog.md) records each release. + +## Where we are + +**Tiroir 0.1.0, released on 29 October 2026, delivers the first milestone.** The +second, *Retrieval*, is next, and is being prepared. The four milestones lead to +[Tiroir 1.0.0](#the-path-to-100). + +| Milestone | Status | What it brings | +|---|---|---| +| [1. Skeleton](#1-skeleton) | Delivered in 0.1.0 | A server that works end to end: install, sign in, search, log | +| [2. Retrieval](#2-retrieval) | Next | Search by meaning, and memory that Claude uses by itself | +| [3. Team](#3-team) | Planned | Several members, safe shared writing, and a guided setup | +| [4. Operations](#4-operations) | Planned | A server you can keep, back up, upgrade and erase from | +| [1.0.0](#the-path-to-100) | Goal | The four milestones delivered and reviewed | + +## The path to 1.0.0 + +Tiroir **1.0.0 is the release at the end of the fourth milestone**: the one where +everything planned for the first version exists, and each milestone has been +checked on a running server and reviewed. + +
    +
  1. + + 0.1.0 + Skeleton + Delivered +
  2. +
  3. + + Retrieval + Search by meaning + Next +
  4. +
  5. + + Team + Shared writing + Planned +
  6. +
  7. + + Operations + Keep it for years + Planned +
  8. +
  9. + + 1.0.0 + The goal + Goal +
  10. +
+ +Each milestone ends in a release numbered `0.x`. Until 1.0.0, treat the releases +as early ones and read the [Changelog](changelog.md) before you upgrade. + +When 1.0.0 is out, you will be able to: + +- install a server on a VPS or on your own machine, with documentation that + takes a new administrator to a connected member in under 30 minutes; +- give each member exactly the stores they should reach, and let them use those + stores from Claude Desktop, Claude on the web and mobile, and Claude Code; +- search by meaning as well as by keyword, and have Claude use the memory + without being asked; +- shape a store with a guided setup, and change its schema later; +- back up a server, restore it on another machine, upgrade it with one command, + and erase what must be erased. + +Some principles hold at every release, and will still hold at 1.0.0: + +- Plain Markdown files in a Git repository are the only source of truth. Every + index can be rebuilt from them. +- Nothing leaves your server except to the mirrors and the external embedding + service you configure, for certificate issuance, and to fetch the public + description of an application that connects. There is no telemetry. +- A member never reaches a store they were not granted, and nothing is written to + a team store without confirmation. +- No memory content appears in commit messages, logs or error messages. + +## 1. Skeleton + +Delivered in 0.1.0 + +The foundations: a server you install, members who sign in, and Claude Desktop +reading and writing their memory. + +- Install the server on a VPS with Docker Compose, behind HTTPS that Caddy + obtains by itself. +- Members sign in with a password you give them; Claude Desktop connects as a + custom connector. +- Stores are Git repositories of Markdown files, created from a preset, and the + bundled `accounting-firm` preset comes with an invented dataset. +- Claude searches by keyword, reads drawers and appends log entries, and each + entry is one commit. + +It was checked on a real VPS: a member added a log entry from Claude Desktop and +found it by search within two seconds. Start with the +[Installation Guide](install/vps.md). + +## 2. Retrieval + +Next + +Finding the right memory, and having Claude use it without being asked. + +- **Search by meaning**, combined with keyword search, in French and in other + languages, with filters by drawer type, drawer, field and date. The default + model is the one that scores best on a published evaluation, within a 4 GB + budget. +- **Claude Code**: a plugin, installed in one command, that recognises the + drawer a prompt is about and puts its summary in front of Claude in under + 300 ms. +- **A memory skill for Claude Desktop**, so that Claude searches Tiroir when it + should and records what is worth remembering without being asked. +- **A second bundled preset, for developers**, next to `accounting-firm`. +- **A folder for your own presets**, that the server reads directly: no copying + presets out of the image, no override file. + +*The check:* on the milestone-one server, the evaluation reports how well +keyword, semantic and combined search find the right entry, and Claude Code and +Claude Desktop use Tiroir on a scripted set of prompts. + +## 3. Team + +Planned + +From one person's server to an organisation's. + +- **Several members with different access**: each member reaches only the stores + they were granted, read-only or read-write. +- **Safe shared writing**: a write to a team store is shown to the member and + recorded only after they confirm, and two members writing at once lose + nothing. +- **Members create drawers and update summaries from Claude.** An update is + proposed, shown as a change, and applied after a person confirms it. +- **A guided setup**: Claude interviews a member in their language, proposes a + schema, shows what it will create and writes it only after they agree. A + non-developer ends with a working store without editing a file. +- **A web administration page** for members, stores and access, instead of the + command line. It never shows memory content. + +*The check:* two members with different grants use one server, each reaching +only their stores, and a non-developer completes the guided setup. + +## 4. Operations + +Planned + +What makes a server safe to keep for years. + +- **Erasure**: purge a drawer from the store, its history, the search index and + a mirror, and mask the links that pointed to it. +- **Links** between drawers, listed for each one. +- **Schema changes**: add or rename a field, rename a drawer type or change the + folder layout on an existing store, previewed before it is applied. +- **Read-only clones and mirrors**: a technical member clones a store, and a + store is mirrored to another Git server. +- **Backup, restore and upgrade**: back up a server, restore it on another + machine and upgrade it with one command, with the data migrated. +- **Documentation complete enough** for a new administrator to go from a fresh + VPS to a connected member in under 30 minutes. + +*The check:* a purge, a migration, a restore on another machine and an upgrade +all succeed. + +## What 0.1.0 cannot do yet + +| Limit in 0.1.0 | Planned in | +|---|---| +| Search is by keyword only. | [Retrieval](#2-retrieval) | +| No Claude Code plugin; no memory skill for Claude Desktop. | [Retrieval](#2-retrieval) | +| Your own presets need copying the bundled ones out of the image. | [Retrieval](#2-retrieval) | +| Members cannot create drawers or update summaries from Claude, only add log entries. | [Team](#3-team) | +| No guided setup: the schema is written by hand. | [Team](#3-team) | +| Administration is by command line only. | [Team](#3-team) | +| The schema of an existing store cannot be changed. | [Operations](#4-operations) | +| No backup, restore or upgrade commands, and no erasure. | [Operations](#4-operations) | + +## Not planned for now + +- A web interface to read or edit memory. The web administration page manages + members, stores and access only; reading and editing memory could be studied + later. +- Hosting Tiroir for several organisations: one server serves one organisation. +- Permissions per drawer: access is per store, so content with a different + readership goes in a different store. +- Single sign-on with an outside identity provider. +- Hosts other than Claude: the connection is designed to allow them later. +- Writing to a store through Git: clones and mirrors are read-only. + +The full list, and the reasons, are in the project's requirements on +[GitHub](https://github.com/ancelin-code/tiroir). diff --git a/zensical.toml b/zensical.toml index bf13ec1..d694085 100644 --- a/zensical.toml +++ b/zensical.toml @@ -1,13 +1,14 @@ # The user documentation site, built by `mise run docs:build` and published to # GitHub Pages from `develop` by .github/workflows/docs.yml. [project] -site_name = "tiroir" +site_name = "Tiroir" site_description = "Configurable, scoped memory for AI agents, served to your team from your own server." site_url = "https://ancelin-code.github.io/tiroir/" repo_url = "https://github.com/ancelin-code/tiroir" edit_uri = "edit/develop/docs" copyright = "Apache-2.0" strict = true +extra_css = ["assets/extra.css"] # The site is the user documentation only: the brief, the research notes and # the milestone notes stay in the repository, out of the site. @@ -19,14 +20,53 @@ milestones/ nav = [ { "Home" = "index.md" }, - { "Install (VPS)" = "install/vps.md" }, - { "Connect (Claude Desktop)" = "connect/claude-desktop.md" }, - { "Reference (CLI)" = "reference/cli.md" }, + { "Server Installation" = [ + { "Installation Guide" = "install/vps.md" }, + { "Custom Schema" = "install/custom-schema.md" }, + ] }, + { "Client Installation" = [ + { "Connect Claude Desktop" = "connect/claude-desktop.md" }, + ] }, + { "Reference" = [ + { "CLI Reference" = "reference/cli.md" }, + { "Schema Reference" = "reference/schema.md" }, + ] }, + { "Roadmap" = "roadmap.md" }, + { "Changelog" = "changelog.md" }, ] +[project.theme] +logo = "assets/logo.svg" +favicon = "assets/logo.svg" +# A copy button at the top right of every code block. +features = ["content.code.copy"] + +# Light and dark palettes, following the visitor's system preference first. +[[project.theme.palette]] +media = "(prefers-color-scheme)" +toggle.icon = "lucide/sun-moon" +toggle.name = "Switch to light mode" + +[[project.theme.palette]] +media = "(prefers-color-scheme: light)" +scheme = "default" +primary = "brown" +accent = "amber" +toggle.icon = "lucide/sun" +toggle.name = "Switch to dark mode" + +[[project.theme.palette]] +media = "(prefers-color-scheme: dark)" +scheme = "slate" +primary = "brown" +accent = "amber" +toggle.icon = "lucide/moon" +toggle.name = "Switch to system preference" + [project.plugins.llmstxt] -markdown_description = "tiroir is a self-hosted memory server for teams of AI agents: install it on a VPS, connect Claude Desktop, and administer it from the command line." +markdown_description = "Tiroir is a self-hosted memory server for teams of AI agents: install it on a VPS, connect Claude Desktop, and administer it from the command line." [project.plugins.llmstxt.sections] -"Get started" = ["index.md", "install/vps.md", "connect/claude-desktop.md"] -Reference = ["reference/cli.md"] +"Get started" = ["index.md", "install/vps.md", "connect/claude-desktop.md", "install/custom-schema.md"] +Reference = ["reference/cli.md", "reference/schema.md"] +Project = ["roadmap.md", "changelog.md"]