granite-mem 0.1.9 → 0.1.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Vibe Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,26 @@
 # Granite
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/granite-mem"><img src="https://img.shields.io/npm/v/granite-mem?color=111111" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/granite-mem"><img src="https://img.shields.io/npm/dm/granite-mem?color=111111" alt="npm downloads"></a>
+  <a href="https://github.com/The-Vibe-Company/Granite/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/The-Vibe-Company/Granite/ci.yml?branch=main&label=tests&color=111111" alt="CI status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/The-Vibe-Company/Granite?color=111111" alt="MIT license"></a>
+  <a href="https://github.com/The-Vibe-Company/Granite/stargazers"><img src="https://img.shields.io/github/stars/The-Vibe-Company/Granite?style=social" alt="GitHub stars"></a>
+</p>
+
 > **The personal OS your agent runs on.**
-> Markdown files. One SQLite index. A contract your agent already knows how to operate.
+> Markdown files. One SQLite index. A typed contract your agent already knows how to operate.
+
+<p align="center">
+  <img src="docs/screenshots/granite-graph.png" alt="Granite constellation graph" width="720">
+</p>
 
 <p align="center">
-  <img src="docs/screenshots/granite-note.png" alt="Granite note view" width="720">
+  <b>Install it with your agent.</b> Or run it standalone as a local markdown knowledge graph.
 </p>
 
 <p align="center">
-  <b>Install in one prompt.</b> Your agent does the rest.
+  <a href="#your-vault-in-the-cloud"><img src="https://img.shields.io/badge/☁️_Deploy_your_Granite-one_command,_sleeps_when_idle-111111?style=for-the-badge" alt="Deploy your Granite"></a>
 </p>
 
 ---
@@ -33,69 +45,69 @@ Sixty seconds later you have a live vault, a connected agent that **knows how to
 
 That's the thesis of this project.
 
-## What is Granite?
-
-Granite is a **local-first operating substrate** for the human + agent duo:
-
-- **Files you own.** Plain markdown with YAML frontmatter in `~/.granite`. No database, no lock-in, `git` works.
-- **Typed contracts, not folders.** Note types declare fields, hooks, indexed queries, and lifecycles. Create a `meeting` and the org stub, date default, and backlinks all fall into place automatically — deterministically, no LLM involved.
-- **Agent-native MCP.** The server *teaches* methodology: tools organized along `orient → research → inspect → plan → mutate`. Drop any MCP-capable LLM onto the vault and it can operate it without a system prompt.
-- **Hard boundary.** **No LLM, no embeddings, no scheduler inside Granite.** All intelligence lives in your agent. Granite is the disk, the schema, and the rules — never the brain.
-
-One loop: **capture → compile → query → output → lint**.
+## See it
+
+<table>
+  <tr>
+    <td width="50%">
+      <img src="docs/screenshots/granite-graph.png" alt="Granite constellation graph">
+      <br>
+      <sub><b>Constellation graph.</b> Browse the vault as communities, hubs, and links.</sub>
+    </td>
+    <td width="50%">
+      <img src="docs/screenshots/granite-search.png" alt="Granite command palette search">
+      <br>
+      <sub><b>Command palette.</b> Search the vault and jump straight into the graph context.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%">
+      <img src="docs/screenshots/granite-preview.png" alt="Granite note preview">
+      <br>
+      <sub><b>Graph-aware reading.</b> Preview notes without losing the surrounding context.</sub>
+    </td>
+    <td width="50%">
+      <img src="docs/screenshots/granite-note.png" alt="Granite reader view">
+      <br>
+      <sub><b>Floating reader.</b> Open a note without leaving the constellation.</sub>
+    </td>
+  </tr>
+</table>
 
-## Install prompts (copy-paste)
-
-### Claude Code / Claude Desktop
-
-```
-Install Granite for me:
-  npm install -g granite-mem
-  granite init --template founder-os
-  claude mcp add granite -- granite mcp --vault ~/.granite
-After restart, call granite_wakeup and tell me what the vault looks like.
-```
-
-### Cursor
+## What is Granite?
 
-```
-Run these commands, then add Granite to .cursor/mcp.json:
-  npm install -g granite-mem
-  granite init --template founder-os
+A local-first markdown store with an opinionated flow. **No AI inside** — just plain files on disk, indexed by SQLite, queried deterministically.
 
-Append to .cursor/mcp.json:
-  { "mcpServers": { "granite": { "command": "granite", "args": ["mcp", "--vault", "~/.granite"] } } }
+- **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.
 
-Reload Cursor. Then call granite_wakeup.
-```
+Your agent brings the intelligence. Granite holds the ground truth.
 
-### ChatGPT / any HTTP-MCP client
+## Try it standalone
 
-```
-Start the Granite MCP over HTTP:
-  granite mcp --transport http --host 127.0.0.1 --port 3321
-Then register http://127.0.0.1:3321 as an MCP server in your client.
+```bash
+npm install -g granite-mem
+granite init
+granite serve
 ```
 
-Every one of these leaves you with the same outcome: your agent owns the loop.
+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.
 
-## What your agent can do with it
+## Agent-native MCP
 
-Once connected, these are real prompts that work **out of the box**:
+> "A thin MCP server exposes capabilities. A strong MCP server shapes behavior."
 
-> **"Process my inbox."**
-> The agent calls `granite_wakeup`, lists inbox notes, classifies each, rewrites them as durable `note`s, links them to existing people/orgs, and promotes `review_state: draft → reviewed`.
+Granite's MCP surface is intention-first:
 
-> **"Summarize everything I know about [[acme-corp]] before the meeting at 3pm."**
-> `granite_compile_context` returns a typed brief: identity, recent meetings, people, open threads, links into related syntheses. One tool call. No fuzzy matching.
+- `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
 
-> **"I just talked to Alice from Acme about local-first sync."**
-> `granite_capture_knowledge` creates a `meeting`, fills `date: today` via a hook, resolves `organization: Acme` to a slug (creates a stub if missing), links `attendees: [[alice]]`, and suggests three follow-up notes.
-
-> **"Garden the vault."**
-> `granite_plan_garden` returns the highest-leverage clusters to revisit. The agent opens the top three, revises them, and flags lifecycle transitions (`stale_days`) for your review.
-
-Every one of those is a single MCP round-trip, deterministic, auditable in `git log`.
+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
 
@@ -125,7 +137,7 @@ note_types:
 - `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
 
-Add a type when your life has a new shape. The core stays small.
+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).
 
 ## Templates
 
@@ -134,7 +146,7 @@ granite init                          # minimal: note / source / synthesis / out
 granite init --template founder-os    # + person / organization / meeting / learning
 ```
 
-`founder-os` is the full personal-OS starter: people you talk to, orgs you work with, meetings you had, things you learned. Nine types, already wired with hooks, indexed fields, and lifecycles. Open `templates/founder-os.yml` — it's 150 lines of pure YAML.
+`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 hard boundary
 
@@ -166,10 +178,138 @@ Your agent reads these before writing and sets them as it works. You inherit a f
 - 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 serve` gives you a local web UI — browse, search, explore local and cloud graphs
+- `granite daemon start` runs MCP + web UI in one background process
+
+## Your vault in the cloud
+
+One command deploys a personal serverless Granite on [Fly.io Sprites](https://sprites.dev): a real persistent filesystem, an MCP endpoint that **wakes on request** (100–500 ms warm) and **sleeps when idle**. Idle cost ≈ storage only — a markdown vault is a few MB, so cents per month.
+
+```bash
+export SPRITES_TOKEN=…   # from sprites.dev — your account, your sprite, your data
+npx granite-mem deploy
+```
+
+Or store the Sprites API token once in a user-scoped Granite credentials file:
+
+```bash
+granite deploy login --token <sprites-token>
+```
+
+That writes `~/.granite/config/sprites.json` (mode `0600` where supported). It works on macOS, Linux, and Windows via the user's home directory. Commands resolve credentials in this order: `--token`, `SPRITES_TOKEN`, then the stored file. Remove it with `granite deploy logout`.
+
+That prints an MCP URL + bearer token ready to paste into Claude Code or Cursor:
+
+```bash
+claude mcp add --transport http granite https://<your-sprite>.sprites.app/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+There is no central admin, no Granite cloud account, no relay: `granite deploy` provisions a sprite **you** own and pay for directly.
+
+Manage instances from any machine after `deploy login`, or with `SPRITES_TOKEN`:
+
+```bash
+granite deploy login --token <sprites-token>
+granite deploy work            # a second instance (own vault, own token, own URL)
+granite deploy list            # all instances: version, health, MCP URL
+granite deploy status --show-token
+granite deploy                 # re-run = upgrade that instance to your CLI version
+granite deploy --all           # bulk remote update of every instance
+granite deploy destroy work    # permanent — asks for confirmation
+```
+
+Browse local and deployed vaults from the same local UI:
+
+```bash
+SPRITES_TOKEN=… granite serve
+```
+
+`granite serve` discovers your managed Sprites using `SPRITES_TOKEN` or the stored `~/.granite/config/sprites.json` token. It keeps MCP bearer tokens on the local server and proxies read-only graph/search/note requests to the selected cloud instance. Use `granite serve --no-cloud` to browse only the local vault.
+
+Notes:
+
+- Document parsing (PDF/DOCX/XLSX/PPTX) is **disabled in cloud deployments** (`GRANITE_DISABLE_DOCUMENT_PARSING=1`). Extract and import documents on your local Granite.
+- Cloud instances expose MCP plus an authenticated read-only web API for the local UI switcher; note creation in the web UI remains local-only.
+- The Sprites API token is local user configuration at `~/.granite/config/sprites.json`; it is not written to the vault notes and is excluded from Granite sync manifests.
+- The vault lives at `/home/sprite/.granite` on the sprite, on durable object-storage-backed disk. There is no export/backup command in v1 — treat the sprite as the single copy for now.
+
+### Advanced: run the HTTP MCP server yourself
+
+Granite can expose the MCP server over HTTP anywhere you can run Node. When binding outside localhost, a bearer token is required:
+
+```bash
+export GRANITE_MCP_TOKEN="$(openssl rand -hex 32)"
+granite mcp --vault ~/.granite \
+  --transport http \
+  --host 0.0.0.0 \
+  --port 3321 \
+  --web-api
+```
+
+Clients must send the token on every MCP request:
+
+```bash
+claude mcp add --transport http granite https://granite.example.com/mcp \
+  --header "Authorization: Bearer $GRANITE_MCP_TOKEN"
+```
+
+A generic `Dockerfile` is included for self-hosting on your own infra (build it yourself; no public image is published). The `/health` endpoint is unauthenticated for platform checks. Do not expose `granite serve` or the web UI port `4321` on the public internet; the web UI is local-only and has no authentication. If `--web-api` is enabled on the HTTP MCP server, `/api/*` and `/assets/*` are guarded by the same bearer token as `/mcp`.
+
+## Direct sync
+
+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.
+
+```bash
+# Machine A
+granite sync access grant ipad --role read
+granite sync access grant desktop --role write
+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:
+
+```bash
+granite sync config --policy primary-wins --primary-this-device
+```
+
+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:
+
+```bash
+granite mcp --vault ~/.granite --role read
+granite mcp --vault ~/.granite --role write
+```
 
 For the full CLI, run `granite --help`. For development, see [CLAUDE.md](CLAUDE.md).
 
+## Roadmap & status
+
+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.
+
+Read [CHANGELOG.md](CHANGELOG.md) for release history. The product boundary stays fixed: Granite stores and indexes local knowledge; agents bring the intelligence.
+
+## Contributing
+
+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.
+
+> 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)
+
 ## Philosophy
 
 - local-first beats cloud dependence for personal memory