granite-mem 0.1.8 → 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,289 +1,247 @@
 # Granite
 
-> A local-first markdown memory system for humans and agents.
-
-Granite is a simple PKM tool built around plain Markdown files, a small set of opinionated note types, and a fast loop for turning raw notes into useful memory.
-
-Most PKM tools give you a blank canvas. Granite gives you a working system:
-
-- capture quickly
-- structure ideas without over-designing your workflow
-- keep sources, durable notes, syntheses, and outputs connected
-- surface what to connect or write next
-- stay fully local, scriptable, and agent-friendly
-
-If you want a flexible framework, there are already many options. Granite is for people who want plain files, strong defaults, and a memory system that starts helping immediately.
-
-![Granite note view](docs/screenshots/granite-note.png)
-
-## Why Granite
-
-Granite is built around a simple loop:
-
-`capture -> link -> recommend -> resurface`
-
-That means:
-
-- your notes live as plain Markdown files with YAML frontmatter
-- the index is derived state, not the source of truth
-- the default note types create just enough structure to stay useful
-- custom note types are easy to add in `granite.yml`
-- the CLI is predictable for both humans and agents
-- the local web UI makes the vault browseable without adding cloud lock-in
-
-Granite is opinionated where it matters and flexible where it should be.
-
-## What Makes It Different
-
-### 1. Simple by default
-
-Granite ships with a small working model instead of an empty workspace:
-
-- `note` for durable ideas
-- `source` for imported or observed source material
-- `synthesis` for durable compiled knowledge
-- `output` for audience-specific deliverables
-
-`note -> synthesis -> output`
-
-This is enough structure to make your notes connect naturally, without forcing you into a heavyweight system.
-
-### 2. Custom types without losing the plot
-
-You can add your own note types in `granite.yml`, but Granite still works out of the box. The product stays simple because the core model is small and every type shares the same mechanics: folder, template, line limit, guidance, and slug strategy.
-
-### 3. Agent-native, not just agent-compatible
-
-Granite is designed to be easy for agents to read and act on:
-
-- notes are plain files
-- metadata is explicit
-- commands support `--json`
-- Granite ships with an MCP server
-- vault structure is predictable
-- search, backlinks, and recommendations are available from the CLI
-
-It works well as a personal system, and it also works as a memory layer for coding agents, assistants, or local automation.
-
-## Quickstart
-
-Clone the repo and install dependencies:
-
-```bash
-git clone https://github.com/The-Vibe-Company/Granite
-cd Granite
-npm install
-npm run build
-npm link
-```
-
-Create the default vault in `~/.granite` and start capturing:
+<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 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">
+  <b>Install it with your agent.</b> Or run it standalone as a local markdown knowledge graph.
+</p>
+
+---
+
+## The wow moment
+
+Paste this into **Claude Code**, **Cursor**, or any MCP-capable agent:
+
+````
+Install Granite as my personal OS.
+
+1. `npm install -g granite-mem`
+2. `granite init --template founder-os`  (vault at ~/.granite)
+3. `claude mcp add granite -- granite mcp --vault ~/.granite`
+4. Restart yourself so the MCP server loads.
+5. Call `granite_wakeup`, then propose three notes you would write
+   first based on what you know about me so far. Capture them as
+   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.
+
+That's the thesis of this project.
+
+## 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>
+
+## 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.
+
+Your agent brings the intelligence. Granite holds the ground truth.
+
+## Try it standalone
 
 ```bash
+npm install -g granite-mem
 granite init
-granite add "Talked to Alice about local-first sync tradeoffs"
-granite new "Local-first sync tradeoffs" --type note
-granite list
-granite search "sync"
-```
-
-Start one long-running interface when you need it:
-
-```bash
-granite serve   # local web UI
-granite mcp     # MCP server for agent clients
-```
-
-`granite new` does more than create a file. It can immediately suggest related links, tags, and the next note to create, which is the core of Granite's value loop.
-
-## Example Workflow
-
-Capture something quickly:
-
-```bash
-granite add "Users want fewer note types, but stronger defaults."
-```
-
-Turn it into a durable note:
-
-```bash
-granite new "Strong defaults beat infinite flexibility" --type note
+granite serve
 ```
 
-Find connections:
+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.
 
-```bash
-granite suggest-links strong-defaults-beat-infinite-flexibility
-granite recommend strong-defaults-beat-infinite-flexibility
-granite backlinks strong-defaults-beat-infinite-flexibility
-```
+## Agent-native MCP
 
-Open the local UI:
+> "A thin MCP server exposes capabilities. A strong MCP server shapes behavior."
 
-```bash
-granite serve
-```
+Granite's MCP surface is intention-first:
 
-Then browse notes, search the vault, inspect backlinks, and explore the graph locally.
+- `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
 
-![Granite graph view](docs/screenshots/granite-graph.png)
+The point is not to give an agent a file browser. The point is to give it a workflow it can follow.
 
-## Custom Note Types
+## Types as active contracts
 
-Granite is intentionally small, but not rigid. Add a type in `granite.yml` when your workflow genuinely needs it:
+This is what makes the agent feel native rather than bolted-on.
 
 ```yaml
+# granite.yml — every note type is an executable contract
 note_types:
-  idea:
-    folder: notes/ideas
-    description: Early product ideas worth pressure-testing
-    template: |
-      ## Problem
-
-      ## Insight
+  meeting:
+    folder: notes/meetings
+    fields:
+      date:         { type: date,     required: true }
+      organization: { type: wikilink, target_types: [organization] }
+      attendees:    { type: wikilink, target_types: [person] }
+    on_create:
+      - { 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
+
+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
 
-      ## Why now
-
-      ## Next step
-    line_limit: 120
-    warn_only: true
-    slug_format: title
-    instructions: Capture the idea clearly, then link it to a source, note, or synthesis.
+```bash
+granite init                          # minimal: note / source / synthesis / output
+granite init --template founder-os    # + person / organization / meeting / learning
 ```
 
-The point is not to create 30 note types. The point is to add a type only when it makes your memory system sharper.
+`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.
 
-## Protocol Fields
+## The hard boundary
 
-Granite keeps the core schema small, but now includes a few shared fields that help both humans and agents work safely in the same vault:
+Granite will **never**:
 
-- `status`: `inbox | active | archived`
-- `source`: `human | agent | extraction`
-- `review_state`: `draft | reviewed | locked`
-- `durability`: `canonical | working | ephemeral`
-- `derived_from`: list of note IDs or slugs used as provenance
+- embed an LLM, run prompts, or hold an API key
+- compute embeddings or ship a vector store
+- run background agents or a scheduler
+- add overlapping CLI/MCP endpoints that blur the loop
 
-These fields are intentionally lightweight:
+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).
 
-- `review_state` is the editorial state
-- `durability` distinguishes durable knowledge from working material or situational outputs
-- `derived_from` is the minimal provenance hook for syntheses and outputs
+## Protocol fields
 
-Granite does not impose a full agent workflow in the core. Richer conventions such as agent traces or synthesis policies are better handled in templates, skills, and team protocol.
+Every note carries five shared fields so humans and agents share ground truth:
 
-## Local-First Architecture
+| 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 |
 
-Granite keeps the source of truth boring and durable:
+Your agent reads these before writing and sets them as it works. You inherit a fully auditable trail.
 
-- notes are Markdown files
-- metadata lives in YAML frontmatter
-- the default vault lives in `~/.granite`
-- vault configuration lives in `~/.granite/granite.yml`
-- full-text search and link resolution are backed by a local SQLite index in `~/.granite/index.db`
-- the index can be rebuilt from the files at any time
+## Local-first, by design
 
-This keeps the system transparent, portable, and inspectable.
+- 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
 
-## Agent-Friendly CLI
+## Direct sync
 
-Many commands support JSON output:
+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
-granite new "Sync constraints" --type note --review-state reviewed --durability canonical --json
-granite list --json
-granite show sync-constraints --json
-granite search "constraints" --json
-granite backlinks sync-constraints --json
-granite recommend sync-constraints --json
-```
-
-That makes Granite a useful substrate for local workflows, scripts, and agent memory.
+# 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
 
-## MCP Server
+# 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
 
-Granite ships with an MCP server so LLM clients can control the vault directly through tools, resources, and prompts.
-
-Start it over stdio for local MCP clients:
-
-```bash
-granite mcp --vault /path/to/vault
+# 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
 ```
 
-Start it over Streamable HTTP:
+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 mcp --transport http --host 127.0.0.1 --port 3321
+granite sync config --policy primary-wins --primary-this-device
 ```
 
-The server exposes:
-
-- tools for vault overview, list/get/search, create/update, backlinks, link suggestions, recommendations, and doctor
-- resources for `granite.yml`, vault overview, note types, and individual notes via `granite://notes/{slug}`
-- prompts for refining notes and reviewing links/next steps
-
-The note payloads exposed through MCP include the shared protocol fields (`status`, `source`, `review_state`, `durability`, `derived_from`) so clients can make safer decisions without Granite embedding any model-specific logic.
+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:
 
-Example stdio client configuration:
-
-```json
-{
-  "command": "granite",
-  "args": ["mcp", "--vault", "/path/to/vault"]
-}
+```bash
+granite mcp --vault ~/.granite --role read
+granite mcp --vault ~/.granite --role write
 ```
 
-## Commands
+For the full CLI, run `granite --help`. For development, see [CLAUDE.md](CLAUDE.md).
 
-```bash
-granite init
-granite new <title> [--type <type>] [--source <source>] [--status <status>] [--review-state <state>] [--durability <durability>] [--derived-from <refs>] [--json]
-granite add [text] [--json]
-granite list [--type <type>] [--json]
-granite edit <slug> [--body <text>] [--append <text>] [--title <title>] [--tag <tags>] [--alias <aliases>] [--status <status>] [--source <source>] [--review-state <state>] [--durability <durability>] [--derived-from <refs>]
-granite open <slug>
-granite show <slug> [--json] [--body]
-granite search <query> [--json]
-granite backlinks <slug> [--json]
-granite suggest-links <slug> [--json]
-granite recommend <slug> [--json]
-granite types
-granite doctor
-granite serve [-p <port>]
-granite mcp [--vault <path>] [--transport <stdio|http>]
-```
+## Roadmap & status
 
-## Development
+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.
 
-```bash
-npm run build
-npm run dev
-npm run test
-npm run test:watch
-npm run lint
-```
+Read [CHANGELOG.md](CHANGELOG.md) for release history. The product boundary stays fixed: Granite stores and indexes local knowledge; agents bring the intelligence.
 
-Run a single test file:
+## Contributing
 
-```bash
-npx vitest run test/core/note.test.ts
-```
+Issues and focused PRs are welcome.
 
-Run the CLI without building:
+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.
 
-```bash
-npx tsx src/index.ts <command>
-```
+> 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
 
-Granite is built on a few beliefs:
-
 - local-first beats cloud dependence for personal memory
-- plain Markdown beats proprietary formats
-- strong defaults beat blank canvases
-- relationships between notes matter more than visual chrome
-- a good PKM should help you decide what to connect or write next
+- plain markdown beats proprietary formats
+- **types as active contracts** beat types as folders
 - tools for humans should also be legible to agents
-- protocol belongs in the core, agent policy belongs outside it
+- protocol belongs in the core; **agent policy belongs outside it**
+- a personal OS is a thing you own — not a thing you rent
+
+---
 
-If that sounds right, Granite is the tool.
+<p align="center">
+  <sub>Ship your agent a home. Then give it the keys.</sub>
+</p>