granite-mem 0.1.7 → 0.1.9

package/README.md

@@ -1,269 +1,186 @@
 # Granite
 
-> A local-first markdown memory system for humans and agents.
+> **The personal OS your agent runs on.**
+> Markdown files. One SQLite index. A contract your agent already knows how to operate.
 
-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.
+<p align="center">
+  <img src="docs/screenshots/granite-note.png" alt="Granite note view" width="720">
+</p>
 
-Most PKM tools give you a blank canvas. Granite gives you a working system:
+<p align="center">
+  <b>Install in one prompt.</b> Your agent does the rest.
+</p>
 
-- capture quickly
-- structure ideas without over-designing your workflow
-- link people, meetings, projects, and decisions
-- 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.
+## The wow moment
 
-![Granite note view](docs/screenshots/granite-note.png)
+Paste this into **Claude Code**, **Cursor**, or any MCP-capable agent:
 
-## Why Granite
+````
+Install Granite as my personal OS.
 
-Granite is built around a simple loop:
+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.
+````
 
-`capture -> link -> recommend -> resurface`
+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 means:
+That's the thesis of this project.
 
-- 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
+## What is Granite?
 
-Granite is opinionated where it matters and flexible where it should be.
+Granite is a **local-first operating substrate** for the human + agent duo:
 
-## What Makes It Different
+- **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.
 
-### 1. Simple by default
+One loop: **capture → compile → query → output → lint**.
 
-Granite ships with a small working model instead of an empty workspace:
+## Install prompts (copy-paste)
 
-- `fleeting` for quick capture
-- `permanent` for durable ideas
-- `reference` for external sources
-- `person` for people and relationships
-- `meeting` for notes with attendees, decisions, and actions
-- `project` for active work
-- `decision` for durable decision records
+### Claude Code / Claude Desktop
 
-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:
-
-```bash
-granite init
-granite add "Talked to Alice about local-first sync tradeoffs"
-granite new "Local-first sync tradeoffs" --type permanent
-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."
+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.
 ```
 
-Turn it into a durable note:
+### Cursor
 
-```bash
-granite new "Strong defaults beat infinite flexibility" --type permanent
 ```
+Run these commands, then add Granite to .cursor/mcp.json:
+  npm install -g granite-mem
+  granite init --template founder-os
 
-Find connections:
+Append to .cursor/mcp.json:
+  { "mcpServers": { "granite": { "command": "granite", "args": ["mcp", "--vault", "~/.granite"] } } }
 
-```bash
-granite suggest-links strong-defaults-beat-infinite-flexibility
-granite recommend strong-defaults-beat-infinite-flexibility
-granite backlinks strong-defaults-beat-infinite-flexibility
+Reload Cursor. Then call granite_wakeup.
 ```
 
-Open the local UI:
+### ChatGPT / any HTTP-MCP client
 
-```bash
-granite serve
 ```
-
-Then browse notes, search the vault, inspect backlinks, and explore the graph locally.
-
-![Granite graph view](docs/screenshots/granite-graph.png)
-
-## Custom Note Types
-
-Granite is intentionally small, but not rigid. Add a type in `granite.yml` when your workflow genuinely needs it:
-
-```yaml
-note_types:
-  idea:
-    folder: notes/ideas
-    description: Early product ideas worth pressure-testing
-    template: |
-      ## Problem
-
-      ## Insight
-
-      ## Why now
-
-      ## Next step
-    line_limit: 120
-    warn_only: true
-    slug_format: title
-    instructions: Capture the idea clearly, then link it to a project, person, or permanent note.
+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.
 ```
 
-The point is not to create 30 note types. The point is to add a type only when it makes your memory system sharper.
-
-## Local-First Architecture
+Every one of these leaves you with the same outcome: your agent owns the loop.
 
-Granite keeps the source of truth boring and durable:
+## What your agent can do with it
 
-- 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
+Once connected, these are real prompts that work **out of the box**:
 
-This keeps the system transparent, portable, and inspectable.
+> **"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`.
 
-## Agent-Friendly CLI
+> **"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.
 
-Many commands support JSON output:
+> **"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.
 
-```bash
-granite new "Sync constraints" --type permanent --json
-granite list --json
-granite show sync-constraints --json
-granite search "constraints" --json
-granite backlinks sync-constraints --json
-granite recommend sync-constraints --json
-```
+> **"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.
 
-That makes Granite a useful substrate for local workflows, scripts, and agent memory.
+Every one of those is a single MCP round-trip, deterministic, auditable in `git log`.
 
-## MCP Server
+## Types as active contracts
 
-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
-```
+This is what makes the agent feel native rather than bolted-on.
 
-Start it over Streamable HTTP:
+```yaml
+# granite.yml — every note type is an executable contract
+note_types:
+  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.
+
+## Templates
 
 ```bash
-granite mcp --transport http --host 127.0.0.1 --port 3321
+granite init                          # minimal: note / source / synthesis / output
+granite init --template founder-os    # + person / organization / meeting / learning
 ```
 
-The server exposes:
+`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.
 
-- 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 hard boundary
 
-Example stdio client configuration:
+Granite will **never**:
 
-```json
-{
-  "command": "granite",
-  "args": ["mcp", "--vault", "/path/to/vault"]
-}
-```
+- 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
 
-## Commands
+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).
 
-```bash
-granite init
-granite new <title> [--type <type>] [--json]
-granite add [text] [--json]
-granite list [--type <type>] [--json]
-granite edit <slug>
-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>]
-```
+## Protocol fields
 
-## Development
+Every note carries five shared fields so humans and agents share ground truth:
 
-```bash
-npm run build
-npm run dev
-npm run test
-npm run test:watch
-npm run lint
-```
+| 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 |
 
-Run a single test file:
+Your agent reads these before writing and sets them as it works. You inherit a fully auditable trail.
 
-```bash
-npx vitest run test/core/note.test.ts
-```
+## Local-first, by design
 
-Run the CLI without building:
+- 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
 
-```bash
-npx tsx src/index.ts <command>
-```
+For the full CLI, run `granite --help`. For development, see [CLAUDE.md](CLAUDE.md).
 
 ## 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**
+- 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>