granite-mem 0.1.9 → 0.1.11

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,22 @@
 # 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-note.png" alt="Granite note view" width="720">
+  <img src="docs/screenshots/granite-graph.png" alt="Granite constellation graph" width="720">
 </p>
 
 <p align="center">
-  <b>Install in one prompt.</b> Your agent does the rest.
+  <b>Install it with your agent.</b> Or run it standalone as a local markdown knowledge graph.
 </p>
 
 ---
@@ -33,69 +41,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**.
-
-## 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.
-```
+## 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>
 
-### 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
 
+```bash
+npm install -g granite-mem
+granite init
+granite serve
 ```
-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.
-```
-
-Every one of these leaves you with the same outcome: your agent owns the loop.
 
-## What your agent can do with it
+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.
 
-Once connected, these are real prompts that work **out of the box**:
+## Agent-native MCP
 
-> **"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`.
+> "A thin MCP server exposes capabilities. A strong MCP server shapes behavior."
 
-> **"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's MCP surface is intention-first:
 
-> **"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.
+- `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
 
-> **"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 +133,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 +142,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
 
@@ -167,9 +175,62 @@ Your agent reads these before writing and sets them as it works. You inherit a f
 - 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
+
+## 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