granite-mem 0.1.11 → 0.1.13

package/README.md

@@ -9,19 +9,21 @@
 </p>
 
 > **The personal OS your agent runs on.**
-> Markdown files. One SQLite index. A typed contract your agent already knows how to operate.
+> Give your agent a memory it can't hallucinate: plain markdown + SQLite full-text search + a typed contract it already knows how to operate. No LLM inside. Your agent brings the intelligence; Granite holds the ground truth.
 
 <p align="center">
   <img src="docs/screenshots/granite-graph.png" alt="Granite constellation graph" width="720">
 </p>
 
 <p align="center">
-  <b>Install it with your agent.</b> Or run it standalone as a local markdown knowledge graph.
+  <code>npm install -g granite-mem</code>
 </p>
 
 ---
 
-## The wow moment
+**Jump to:** [The 60-second setup](#the-60-second-setup) · [Install it yourself](#or-install-it-yourself) · [How it works](#how-it-works) · [Why not Obsidian, Notion, or a vector store?](#why-not-obsidian-notion-or-a-vector-store) · [See it](#see-it) · [Types are contracts](#types-are-contracts-not-folders) · [The MCP server](#wired-for-agents-the-mcp-server) · [What Granite will never do](#what-granite-will-never-do) · [Beyond one machine](#beyond-one-machine) · [The full CLI](#the-full-cli) · [FAQ](#faq) · [Philosophy](#philosophy)
+
+## The 60-second setup
 
 Paste this into **Claude Code**, **Cursor**, or any MCP-capable agent:
 
@@ -37,9 +39,69 @@ Install Granite as my personal OS.
    drafts with --source agent.
 ````
 
-Sixty seconds later you have a live vault, a connected agent that **knows how to use it**, and three starter notes in `~/.granite/notes/`. No system prompt. No config. No cloud.
+Sixty seconds later: a live vault, an agent that knows how to operate it, and its first three notes on disk in `~/.granite/notes/`. No system prompt. No config. No cloud.
+
+That's the thesis of this project. No agent handy? Granite is a complete tool on its own:
+
+## Or install it yourself
+
+```bash
+npm install -g granite-mem
+granite init                        # note / source / synthesis / output
+granite new "Ideas worth stealing"
+granite search "steal"
+granite serve                       # web UI + constellation graph
+```
+
+Add `--template founder-os` to `init` when you want a full personal OS from the start: `person`, `organization`, `meeting`, and `learning` on top of the four defaults — eight types already wired with hooks, indexed fields, and lifecycles, in [150 lines of pure YAML](templates/founder-os.yml).
+
+Everything Granite writes is a plain `.md` file with YAML frontmatter. Close the laptop, `git init` the vault, open the folder in any editor — it's just files.
+
+## How it works
+
+Granite is a **deterministic substrate** for knowledge: markdown files as the source of truth, a SQLite index as derived state, and one fixed loop imposed on top. The intelligence is not in Granite — it's in whatever agent (or human) operates it.
 
-That's the thesis of this project.
+```
+              ┌──────────────────────────────────────────┐
+              │        your agent  ·  the brains         │
+              └────────────────────┬─────────────────────┘
+                                   │  MCP · CLI · web UI
+              ┌────────────────────▼─────────────────────┐
+              │                 GRANITE                  │
+              │                                          │
+              │   capture ─▶ compile ─▶ query ─▶ output  │
+              │      ▲                             │     │
+              │      └──────────── lint ◀──────────┘     │
+              │                                          │
+              │   .md files     SQLite FTS5   wikilinks  │
+              │   (truth)       (derived)     (graph)    │
+              └──────────────────────────────────────────┘
+```
+
+- **Markdown is truth.** Every note is `<folder>/<slug>.md` with YAML frontmatter. Nothing you can't read in `cat`.
+- **The index is disposable.** Full-text search, backlinks, and typed queries live in `.granite/index.db` — rebuilt from the files at any time.
+- **Wikilinks are the graph.** `[[a-note]]` in any body resolves slug → title → alias, and the backlink graph falls out for free.
+
+> Karpathy asked for *"an incredible new product instead of a hacky collection of scripts"* for [LLM knowledge bases](https://x.com/karpathy/status/2039805659525644595).
+>
+> This is our answer.
+
+## Why not Obsidian, Notion, or a vector store?
+
+Granite doesn't compete with your note app. It competes with the pile of scripts you were about to write.
+
+|                                                | **Granite** | Obsidian  | Notion    | Vector memory | Plain files |
+| ---------------------------------------------- | :---------: | :-------: | :-------: | :-----------: | :---------: |
+| Plain markdown on disk                         | ✅          | ✅        | ❌        | ❌            | ✅          |
+| Typed schemas with hooks & lifecycles          | ✅          | plugins   | databases | ❌            | ❌          |
+| Agent-native MCP workflow                      | ✅          | community | limited   | ✅            | ❌          |
+| Deterministic retrieval (no embeddings)        | ✅          | ✅        | ❌        | ❌            | `grep`      |
+| Structured queries over indexed fields         | ✅          | plugins   | ✅        | ❌            | ❌          |
+| Provenance on every note                       | ✅          | ❌        | ❌        | partial       | ❌          |
+| Offline, no account, no telemetry              | ✅          | ✅        | ❌        | ❌            | ✅          |
+| Git-friendly                                   | ✅          | ✅        | ❌        | ❌            | ✅          |
+
+Obsidian is a great editor for humans. Vector memory is a great cache for agents. Granite is the shared substrate both can operate.
 
 ## See it
 
@@ -70,47 +132,11 @@ That's the thesis of this project.
   </tr>
 </table>
 
-## What is Granite?
-
-A local-first markdown store with an opinionated flow. **No AI inside** — just plain files on disk, indexed by SQLite, queried deterministically.
-
-- **Imposed flow.** Capture, compile, query, output, lint. The shape is fixed; the content is yours.
-- **Four default note types** — `note`, `source`, `synthesis`, `output`. Add your own in `granite.yml` when your life grows a new shape.
-- **A specialized MCP** that teaches your agent how to use the vault. Drop any MCP-capable agent on it and it knows how to operate, no system prompt required.
+## Types are contracts, not folders
 
-Your agent brings the intelligence. Granite holds the ground truth.
-
-## Try it standalone
-
-```bash
-npm install -g granite-mem
-granite init
-granite serve
-```
-
-That starts with the default knowledge model: `note`, `source`, `synthesis`, and `output`. Add `--template founder-os` when you want people, organizations, meetings, and learnings wired in from the start.
-
-## Agent-native MCP
-
-> "A thin MCP server exposes capabilities. A strong MCP server shapes behavior."
-
-Granite's MCP surface is intention-first:
-
-- `granite_wakeup` to orient
-- `granite_research_topic` to inspect existing knowledge before writing
-- `granite_query` for structured filters over typed notes
-- `granite_compile_context` to assemble a graph-aware brief
-- `granite_plan_garden` to decide what to improve next
-- `granite_capture_knowledge` to write with protocol fields and type contracts
-
-The point is not to give an agent a file browser. The point is to give it a workflow it can follow.
-
-## Types as active contracts
-
-This is what makes the agent feel native rather than bolted-on.
+This is what makes an agent feel native rather than bolted-on. Every note type in `granite.yml` is an executable contract:
 
 ```yaml
-# granite.yml — every note type is an executable contract
 note_types:
   meeting:
     folder: notes/meetings
@@ -122,114 +148,164 @@ note_types:
       - { action: set_default,       field: date, value: "${today}" }
       - { action: resolve_wikilinks, fields: [organization, attendees], auto_stub: true }
     indexed_fields: [date, organization]
-    lifecycle:
-      states: [active, archived]
-      transitions:
-        - { from: active, to: archived, trigger: stale_days, days: 180 }
 ```
 
 - `set_default` — fills `${today}` automatically
 - `resolve_wikilinks + auto_stub` — turns `organization: Acme Corp` into the slug `acme-corp`, creating the org note if missing (with a globally-unique slug so nothing gets silently overwritten)
-- `indexed_fields` — makes `granite_query { type: meeting, where: { date: { gte: "2026-01-01" } } }` O(1) and deterministic
-- `lifecycle` — `granite doctor` surfaces stale notes so gardening never drifts
+- `indexed_fields` — makes `granite_query { type: meeting, where: { date: { gte: "2026-01-01" } } }` fast and deterministic
+- `lifecycle` — declare states and stale-days transitions, and `granite doctor` surfaces drift before it rots
 
-Add a type when your life has a new shape. The core stays small. For the formal protocol, see [docs/GRANITE_OBJECT_STANDARD.md](docs/GRANITE_OBJECT_STANDARD.md).
+On top of its type, **every note carries five protocol fields**, so humans and agents share ground truth:
 
-## Templates
+| Field          | Values                                | Purpose                              |
+|----------------|---------------------------------------|--------------------------------------|
+| `status`       | `inbox` · `active` · `archived`       | operational state                    |
+| `source`       | `human` · `agent` · `extraction`      | who wrote it                         |
+| `review_state` | `draft` · `reviewed` · `locked`       | editorial state                      |
+| `durability`   | `canonical` · `working` · `ephemeral` | keep / may drift / throwaway         |
+| `derived_from` | `[slug, …]`                           | provenance for syntheses and outputs |
+
+Your agent reads these before writing and sets them as it works. You inherit a fully auditable trail. Add a type when your life grows a new shape — the core stays small. For the formal protocol, see [docs/GRANITE_OBJECT_STANDARD.md](docs/GRANITE_OBJECT_STANDARD.md).
+
+## Wired for agents: the MCP server
+
+> "A thin MCP server exposes capabilities. A strong MCP server shapes behavior."
+
+One line connects any MCP-capable agent to your vault:
 
 ```bash
-granite init                          # minimal: note / source / synthesis / output
-granite init --template founder-os    # + person / organization / meeting / learning
+claude mcp add granite -- granite mcp --vault ~/.granite
 ```
 
-`founder-os` is the full personal-OS starter: people you talk to, orgs you work with, meetings you had, things you learned. Eight types, already wired with hooks, indexed fields, and lifecycles. Open `templates/founder-os.yml` — it's 150 lines of pure YAML.
+The surface is intention-first — fourteen tools organized around the workflow, not around files:
+
+| Intent     | Tools                                                                                                          |
+|------------|----------------------------------------------------------------------------------------------------------------|
+| **Orient** | `granite_wakeup` · `granite_research_topic` · `granite_resolve`                                                  |
+| **Read**   | `granite_query` · `granite_compile_context` · `granite_understand_note` · `granite_extract_document`             |
+| **Write**  | `granite_capture_knowledge` · `granite_import_document` · `granite_revise_note` · `granite_dispose_note`         |
+| **Garden** | `granite_plan_garden` · `granite_adjudicate_garden_opportunity` · `granite_list_garden_adjudications`            |
 
-## The hard boundary
+Plus three prompts for the higher-level workflows (`granite_refine_note`, `granite_process_inbox`, `granite_compile_topic`), and resources for raw note and type-contract access. Start the server with `--role read` when an agent should inspect without mutating. An HTTP transport with bearer-token auth is available for remote setups — see [docs/DEPLOY.md](docs/DEPLOY.md).
+
+The point is not to give an agent a file browser. The point is to give it a workflow it can follow.
+
+## What Granite will never do
 
 Granite will **never**:
 
 - embed an LLM, run prompts, or hold an API key
 - compute embeddings or ship a vector store
 - run background agents or a scheduler
+- phone home — no telemetry, no account, no cloud dependency
 - add overlapping CLI/MCP endpoints that blur the loop
 
-This is why your agent can be trusted with write access. The vault is a **deterministic substrate**. The intelligence is yours (or Claude's, or GPT's, or whoever you pay this quarter).
-
-## Protocol fields
-
-Every note carries five shared fields so humans and agents share ground truth:
+This is why your agent can be trusted with write access. The vault is a deterministic substrate. The intelligence is yours (or Claude's, or GPT's, or whoever you pay this quarter).
 
-| Field          | Values                                | Purpose                              |
-|----------------|---------------------------------------|--------------------------------------|
-| `status`       | `inbox` · `active` · `archived`       | operational state                    |
-| `source`       | `human` · `agent` · `extraction`      | who wrote it                         |
-| `review_state` | `draft` · `reviewed` · `locked`       | editorial state                      |
-| `durability`   | `canonical` · `working` · `ephemeral` | keep / may drift / throwaway         |
-| `derived_from` | `[slug, …]`                           | provenance for syntheses and outputs |
+## Beyond one machine
 
-Your agent reads these before writing and sets them as it works. You inherit a fully auditable trail.
+**Cloud, if you want it.** One command deploys a personal serverless Granite on [Fly.io Sprites](https://sprites.dev): wakes on request in 100–500 ms, sleeps when idle, costs cents per month at rest. You own the sprite — there is no Granite cloud, no central admin, no relay.
 
-## Local-first, by design
+```bash
+granite deploy login --token <sprites-token>   # or export SPRITES_TOKEN=…
+granite deploy                                 # prints an MCP URL + bearer token
 
-- Markdown files are the source of truth; the SQLite index in `~/.granite/index.db` is derived state and can be rebuilt at any time
-- no cloud, no telemetry, no account
-- `git init` your vault and you have versioning for free
-- `granite serve` gives you a local web UI — browse, search, explore the graph
-- `granite daemon start` runs MCP + web UI in one background process
+claude mcp add --transport http granite https://<your-sprite>.sprites.app/mcp \
+  --header "Authorization: Bearer <token>"
+```
 
-## Direct sync
+Multiple named instances, bulk upgrades, token rotation, and self-hosting the HTTP MCP server (a generic `Dockerfile` is included) are covered in [docs/DEPLOY.md](docs/DEPLOY.md).
 
-Granite sync is direct machine-to-machine. Run it over LAN, Tailscale, or a private DNS name; there is no relay, hosted worker, billing tier, or cloud authority.
+**Sync, without a relay.** Direct machine-to-machine over LAN, Tailscale, or a private DNS name — with per-device read/write tokens:
 
 ```bash
-# Machine A
-granite sync access grant ipad --role read
-granite sync access grant desktop --role write
+granite sync access grant ipad --role read     # on the serving machine
 granite sync serve --host 0.0.0.0 --port 8765
 
-# Read-only Machine B
 granite sync remote add macbook http://100.x.y.z:8765 --token <read-token>
-granite sync pull macbook
 granite sync watch macbook --direction pull --interval 30
-
-# Write-capable Machine C
-granite sync remote add macbook http://100.x.y.z:8765 --token <write-token>
-granite sync run macbook
-granite sync watch macbook --interval 30
 ```
 
-Conflicts default to manual preservation with `.conflict.<device>.<timestamp>.md` files. For a personal multi-device setup, pick the device that wins conflicts:
+Conflict policies, push/pull details, and access management live in [docs/SYNC.md](docs/SYNC.md).
 
-```bash
-granite sync config --policy primary-wins --primary-this-device
-```
+## The full CLI
 
-MCP is scoped to one vault per server. Launch a read-only MCP server when an agent should inspect a synced vault without mutating it:
+<details>
+<summary><b>Every command, one line each</b></summary>
 
-```bash
-granite mcp --vault ~/.granite --role read
-granite mcp --vault ~/.granite --role write
-```
+| Layer      | Command                    | What it does                                                    |
+|------------|----------------------------|------------------------------------------------------------------|
+| setup      | `granite init`             | create a vault (optionally from a `--template`)                  |
+| setup      | `granite status`           | vault health and what to do next                                 |
+| capture    | `granite new <title>`      | create a typed note                                              |
+| capture    | `granite add [text]`       | quick raw capture (arg or stdin) into the inbox                  |
+| capture    | `granite attach <file>`    | attach an image/video/PDF and get markdown to embed              |
+| capture    | `granite extract <file>`   | raw text from PDF/DOCX/XLSX/PPTX without importing               |
+| capture    | `granite import <file> --content <text>` | attach a document and create a linked source note |
+| query      | `granite list`             | browse notes by type, status, source, date                       |
+| query      | `granite show <slug>`      | read a full note                                                 |
+| query      | `granite search <query>`   | full-text search across the vault                                |
+| query      | `granite open <slug>`      | open a note in `$EDITOR`                                         |
+| query      | `granite wakeup`           | compact vault snapshot for loading agent context                 |
+| compile    | `granite edit <slug>`      | update fields, body, tags, protocol state                        |
+| compile    | `granite backlinks <slug>` | inbound links to a note                                          |
+| compile    | `granite suggest-links <slug>` | unlinked mentions worth linking                              |
+| compile    | `granite recommend <slug>` | what to link, tag, or write next                                 |
+| lint       | `granite doctor`           | broken links, missing fields, stale notes, line violations       |
+| lint       | `granite types`            | show note types and the flow between them                        |
+| serve      | `granite serve`            | local web UI with the constellation graph (port 4321)            |
+| serve      | `granite mcp`              | MCP server (stdio or HTTP; `--role read\|write`)                 |
+| serve      | `granite daemon start`     | MCP + web UI as one background process                           |
+| cloud      | `granite deploy …`         | serverless instances on Fly.io Sprites ([docs](docs/DEPLOY.md))  |
+| sync       | `granite sync …`           | direct multi-device sync ([docs](docs/SYNC.md))                  |
 
-For the full CLI, run `granite --help`. For development, see [CLAUDE.md](CLAUDE.md).
+Run `granite --help` for every flag.
 
-## Roadmap & status
+</details>
 
-Granite is pre-1.0. The current release is **v0.1.9**, with the major agent-native loop pieces now in place: typed contracts, wakeup snapshots, deterministic garden planning, document import, daemon mode, and the constellation graph.
+## FAQ
 
-Read [CHANGELOG.md](CHANGELOG.md) for release history. The product boundary stays fixed: Granite stores and indexes local knowledge; agents bring the intelligence.
+<details>
+<summary><b>Is this an Obsidian replacement?</b></summary>
 
-## Contributing
+No. Your vault is plain markdown with `[[wikilinks]]` — Obsidian opens it just fine. Granite adds the typed contracts, the deterministic index, and the MCP surface on top of files any editor can read.
 
-Issues and focused PRs are welcome.
+</details>
 
-For local development, read [CLAUDE.md](CLAUDE.md). The key product rule is simple: no embedded LLM, no vector store, no autonomous scheduler inside Granite.
+<details>
+<summary><b>Where's the AI?</b></summary>
 
-> Karpathy wrote that there was room for "an incredible new product instead of a hacky collection of scripts" around LLM knowledge bases.
->
-> Granite is the product that answers that call.
->
-> — [@karpathy on LLM knowledge bases](https://x.com/karpathy/status/2039805659525644595)
+In your agent. Granite is deliberately deterministic — that's precisely why an agent can be trusted with write access to it.
+
+</details>
+
+<details>
+<summary><b>No embeddings — how does search work?</b></summary>
+
+SQLite FTS5 for full text, typed queries over indexed fields, and the wikilink graph for structure. Deterministic, explainable, and rebuildable from the files.
+
+</details>
+
+<details>
+<summary><b>Can I use it without an agent?</b></summary>
+
+Yes. The full CLI and the web UI work standalone. The MCP server is one door among three.
+
+</details>
+
+<details>
+<summary><b>What happens to my data if Granite disappears?</b></summary>
+
+Nothing. It's a folder of markdown files. The index is derived and disposable; `git init` the vault and you have versioning and backup for free.
+
+</details>
+
+<details>
+<summary><b>Does anything phone home?</b></summary>
+
+No. No telemetry, no account, no network calls — unless you explicitly deploy to your own sprite, sync to your own machines, or run `granite serve` with cloud credentials configured (use `--no-cloud` to stay fully offline).
+
+</details>
 
 ## Philosophy
 
@@ -240,6 +316,12 @@ For local development, read [CLAUDE.md](CLAUDE.md). The key product rule is simp
 - protocol belongs in the core; **agent policy belongs outside it**
 - a personal OS is a thing you own — not a thing you rent
 
+## Status & contributing
+
+Granite is pre-1.0 and moving fast — see [CHANGELOG.md](CHANGELOG.md) for release history. The product boundary stays fixed: Granite stores and indexes local knowledge; agents bring the intelligence.
+
+Issues and focused PRs are welcome. For local development, read [CLAUDE.md](CLAUDE.md). The key product rule is simple: no embedded LLM, no vector store, no autonomous scheduler inside Granite.
+
 ---
 
 <p align="center">