@geoql/mdr 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Matt Kane (original author, ascorbic/macrodata)
+Copyright (c) 2026 Vinayak Kulkarni (geoql/macrodata fork)
+
+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

@@ -0,0 +1,152 @@
+# @geoql/mdr
+
+> Persistent, self-maintaining memory and autonomous scheduling for coding agents (OpenCode, Claude Code).
+
+[![npm](https://img.shields.io/npm/v/@geoql/mdr)](https://www.npmjs.com/package/@geoql/mdr)
+[![JSR](https://jsr.io/badges/@geoql/mdr)](https://jsr.io/@geoql/mdr)
+[![Pipeline](https://github.com/geoql/mdr/actions/workflows/pipeline.yml/badge.svg)](https://github.com/geoql/mdr/actions/workflows/pipeline.yml)
+[![codecov](https://codecov.io/gh/geoql/mdr/branch/main/graph/badge.svg)](https://codecov.io/gh/geoql/mdr)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Macrodata gives an AI coding agent layered, local-first memory: a searchable journal, entity files for people and projects, always-injected state files, semantic search across every past session, a background daemon for scheduled reminders, and overnight self-maintenance. All memory is plain markdown and JSON on disk — nothing phones home, and the whole system runs inside the agent's existing permission model with no new APIs or attack surface.
+
+## Hard fork of ascorbic/macrodata
+
+`@geoql/mdr` is a **hard fork of [ascorbic/macrodata](https://github.com/ascorbic/macrodata) by [Matt Kane](https://github.com/ascorbic)** (published upstream as [`@macrodata/opencode`](https://www.npmjs.com/package/@macrodata/opencode)). The layered-memory architecture, the tools, the skills, and the design are Matt's work — this fork stands entirely on that foundation.
+
+### Why this fork
+
+- **Node/pnpm runtime alignment.** OpenCode no longer ships Bun. Upstream targets the Bun runtime (`bun:sqlite`, `bun:test`, bundled-Bun daemon); this fork replaces those with Node equivalents (`node:sqlite`) so the plugin runs on the same Node runtime as its host, in a pnpm workspace.
+- **Merged daemon-hardening + incremental-indexing fixes** ([upstream PR #34](https://github.com/ascorbic/macrodata/pull/34), fixes #25). Hung scheduled children can no longer wedge the daemon forever; a heartbeat lets a stale daemon self-heal on the next session.
+- **`@huggingface/transformers` replacing `sharp` postinstall pain** ([upstream PR #35](https://github.com/ascorbic/macrodata/pull/35)). Kills the native-binary postinstall failure under blocked-lifecycle-script package managers. Same model, same 384-dim embeddings; existing indexes stay valid.
+- **Optional remote OpenAI-compatible embeddings** ([upstream PR #36](https://github.com/ascorbic/macrodata/pull/36)). Offload embedding generation to an API instead of running the local model.
+- **Full Vitest suite at 100% coverage.** Migrated off `bun:test`, with a hard statements/branches/functions/lines gate.
+- **geoql release automation.** release-please → npm (OIDC provenance) + JSR, coverage gate, husky/commitlint/lint-staged.
+
+The **data directory (`~/.config/macrodata/`), the MCP server id (`macrodata`), the `macrodata_*` tool names, and the `MACRODATA_*` environment variables are unchanged** from upstream — an existing install keeps its memories and index across the migration.
+
+## Requirements
+
+- macOS or Linux (WSL on Windows is untested).
+- [Node.js](https://nodejs.org/) `>=24.11.0`.
+
+## Installation
+
+### OpenCode
+
+Add the plugin to **`~/.config/opencode/opencode.json`**:
+
+```json
+{
+  "plugin": ["@geoql/mdr@latest"]
+}
+```
+
+Launch OpenCode and ask it to set up Macrodata.
+
+### Claude Code
+
+```bash
+/plugin marketplace add geoql/mdr
+/plugin install refiner@mdr
+```
+
+## What it does
+
+Every session starts with context injection — identity, current projects, daily focus, and recent activity — so the agent knows who you are and what you're doing before you type anything.
+
+- **Working memory (state files).** A small, always-present working set: `identity.md` (how the agent behaves), `human.md` (who you are), `today.md` (daily focus), `workspace.md` (project context), and topic files. State is a bounded working set, byte-capped per section on injection, with a `flags.md` channel that carries items to you across sessions.
+- **Journal.** Observations, decisions, and learnings get appended to a searchable, date-partitioned JSONL journal.
+- **Entities.** People, projects, and researched topics live as markdown files under `entities/`, indexed for semantic search.
+- **Semantic search.** A [Vectra](https://github.com/Stevenic/vectra) vector index over the journal, entities, and past conversations. By default embeddings are generated locally and offline with `all-MiniLM-L6-v2` (384-dim) via [`@huggingface/transformers`](https://github.com/huggingface/transformers.js); optionally offloaded to a remote endpoint.
+- **Conversation analysis.** Indexes past OpenCode and Claude Code sessions so the agent can retrieve relevant context from prior work.
+- **Scheduling & autonomy.** A background daemon (a cron runner built on [croner](https://github.com/hexagon/croner)) fires reminders, morning prep, distillation, and overnight "dream time" reflection through the same agent instance with the same permissions you already granted.
+
+## Architecture
+
+```
+plugins/macrodata/
+├── .claude-plugin/plugin.json   # Claude Code plugin manifest (hooks + MCP server)
+├── opencode/                    # OpenCode plugin variant
+│   ├── index.ts                 # Plugin entry: context injection + tools + daemon supervision
+│   ├── tools.ts                 # macrodata_* memory tools
+│   ├── context.ts               # State-file context builder
+│   ├── search.ts                # Semantic search over the memory index
+│   └── skills/                  # Distill, dreamtime, memory-maintenance, onboarding
+├── src/                         # MCP server + shared core
+│   ├── index.ts                 # MCP server (server id: "macrodata")
+│   ├── daemon.ts                # Scheduler / reminder logic
+│   ├── indexer.ts               # Vectra index management
+│   ├── embeddings.ts            # Local + optional remote embedding generation
+│   └── config.ts                # Root + config-path resolution
+└── bin/
+    ├── macrodata-daemon.ts      # Background daemon entry point
+    └── index-conversations.ts   # One-shot conversation indexer
+```
+
+**Storage** (default `~/.config/macrodata/`):
+
+```
+identity.md          # Agent persona
+state/               # human.md, today.md, workspace.md, flags.md
+entities/            # people/, projects/, topics/ as markdown
+journal/             # date-partitioned JSONL
+.index/              # Vectra embeddings cache
+reminders/           # scheduled reminder definitions
+config.json          # optional (remote embedding provider, etc.)
+```
+
+## Configuration
+
+### Environment variables
+
+| Variable                     | Purpose                                                                                               |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `MACRODATA_ROOT`             | Override the memory root directory (default `~/.config/macrodata`).                                   |
+| `MACRODATA_CONFIG_PATH`      | Override the path to `config.json` (default `~/.config/macrodata/config.json`).                       |
+| `MACRODATA_CHILD_TIMEOUT_MS` | Hard timeout for scheduled agent children before the daemon kills the process group (default 10 min). |
+
+### Remote embedding provider (optional)
+
+By default embeddings run locally and offline. To offload them to an OpenAI-compatible endpoint, add an `embedding` block to `~/.config/macrodata/config.json`:
+
+```json
+{
+  "embedding": {
+    "provider": "openai-compatible",
+    "endpoint": "https://api.example.com/v1",
+    "api_key": "sk-...",
+    "model": "baai/bge-m3",
+    "input_type": "passage",
+    "query_input_type": "query",
+    "batch_size": 64,
+    "extra_body": {}
+  }
+}
+```
+
+Use `api_key_env` instead of `api_key` to read the key from an environment variable. When an `embedding` block is present, the local model is never loaded. Switching to a provider with a different embedding dimension requires rebuilding existing indexes.
+
+## Security
+
+Macrodata runs inside the agent's existing permission model. It uses only the tools you've already installed and approved — no external APIs (unless you opt into a remote embedding endpoint), no third-party skill downloads, no new attack surface. Scheduled tasks run through the same agent instance with the same permissions. The daemon is a simple cron runner that spawns the agent when reminders fire. All state is local markdown and JSON. Nothing phones home.
+
+## Development
+
+```sh
+pnpm install
+pnpm run lint        # oxlint
+pnpm run typecheck   # oxlint --type-aware --type-check
+pnpm run build       # tsdown
+pnpm run coverage    # vitest run --coverage (100% gate)
+```
+
+Requires Node `>=24.11.0` and pnpm `11.9.0`.
+
+## Inspiration
+
+The layered-memory architecture is inspired by [Letta](https://www.letta.com/), and particularly the [Void](https://cameron.stream/blog/void/) bot by Cameron Pfiffer. The ambient-compute and dream-time concepts are inspired by [Strix](https://timkellogg.me/blog/2025/12/15/strix) by Tim Kellogg. These ideas were first explored by Matt Kane in his Acme agent and released as [ascorbic/macrodata](https://github.com/ascorbic/macrodata).
+
+## License
+
+[MIT](./LICENSE) © [Matt Kane](https://github.com/ascorbic) (original author) and [Vinayak Kulkarni](https://vinayakkulkarni.dev) (fork).

package/USAGE.md

@@ -0,0 +1,59 @@
+## How to Use Macrodata Memory
+
+You have access to Macrodata: persistent, layered memory that you control. You can remember who the user is, what they're working on, and how they like to work. You log observations to a journal, maintain entity files, keep a small set of state files that are always in context, and raise flags when something needs the user's attention.
+
+The layers have different jobs. State is the small, always-present working set. The journal and entities are your durable long-term memory — reliable and searchable, not in context until you pull them. Put each thing where it belongs and trust the system to hold it. You do not need to keep everything in front of you to avoid losing it; that's what the journal is for.
+
+### State Files
+
+These are injected into context every session, so space is scarce and **each file has a budget** (a screenful — a few hundred words). Anything over budget is **truncated at injection** with a marker, so an oversized file doesn't help you — it just hides its own tail. Treat state as a _working set_, not a log: only what's live and load-bearing _right now_.
+
+This means eviction is part of the job, not a failure. When an item is resolved, gone quiet, or aging into history, **move the detail to the journal or an entity file and cut it down to a one-line pointer, or drop it**. Pruning state is not losing information — the information lives in the journal/entities; you're just clearing your desk. A state file you only ever append to is broken.
+
+**`state/today.md`** — focus for the session. Current priorities, what you're on right now, brief carryover. Roll it over each day; yesterday's detail goes to the journal.
+
+**`state/workspace.md`** — active projects and open threads, each as a _one-line_ status with a pointer (`entities/projects/x.md`, or "search: <term>") for the detail. Not a project history — the history is in entities and the journal.
+
+**`state/flags.md`** — things that need the user. See below.
+
+**`state/human.md`** — who the user is: preferences, communication style, work context, timezone. Update when you learn something durable about them.
+
+**`state/identity.md`** — who _you_ are: persona, values, learned patterns, how you operate. Mostly stable; revise during reflection or when your values genuinely shift.
+
+### Flags — reaching the user
+
+`state/flags.md` is how something crosses from your autonomous/background runs into the user's next interactive session. If you find a bug, hit a decision only they can make, or finish something awaiting their review — and you can't act on it yourself — it goes here. **Without this, your findings die in a file they never open.** That's the single most important thing this memory does: surface the signal.
+
+Keep each flag to **one line + a pointer** to the journal/entity holding the full writeup. Don't restate the whole investigation here every run — that's the hoarding trap. Clear flags when they're addressed or no longer true; a stale flag list is noise and the user stops reading it.
+
+### Entities
+
+Create `entities/{type}/{name}.md` for persistent knowledge that deserves its own file — and **this is where project/topic detail belongs**, not state. They're indexed for semantic search; a list of them is kept in working memory, but you read/create/maintain them proactively. This is your filing system; keep it organized and let it grow. During distillation you review and consolidate.
+
+**When to create one:**
+
+- Significant details about a person → `entities/people/name.md`
+- A project with enough context to track → `entities/projects/name.md`
+- A topic you've researched in depth → `entities/topics/name.md`
+- Anything long-form or worth maintaining → `entities/{category}/name.md`
+
+**Create new categories freely** — just make the directory.
+
+### Journal — your durable memory
+
+`log_journal(topic, content)` is reliable long-term storage: append-only, timestamped, and **retrievable via `search_memory`**. Writing something to the journal is _remembering_ it, not forgetting it — searching is how recall normally works, not a last resort. So log freely and in detail: decisions and why, things learned, events, debugging traces, the full version of anything you're about to compress out of state. Use entity files instead when you expect to _update_ the thing later; the journal is for point-in-time records.
+
+### Search
+
+`search_memory` finds context across entities and journal. Search before saying you don't know something — it may already be in your memory. Stuck on a problem? Search for how you handled similar ones. Recall is a normal first move, not a fallback.
+
+### Quick Reference
+
+| What you have                  | Where it goes                                  |
+| ------------------------------ | ---------------------------------------------- |
+| Needs the user's eyes/action   | `state/flags.md` (one line + pointer)          |
+| Live, load-bearing right now   | State file (briefly)                           |
+| Persistent, evolving knowledge | Entity file                                    |
+| Point-in-time record / detail  | Journal entry                                  |
+| Resolved or aging item         | Out of state → journal/entity, leave a pointer |
+| Future / recurring task        | `schedule`                                     |

package/bin/detect-user.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+#
+# Detect user information for onboarding
+# Outputs JSON with all detected info
+#
+
+# System info
+USERNAME=$(whoami)
+FULLNAME=$(id -F 2>/dev/null || getent passwd "$USERNAME" 2>/dev/null | cut -d: -f5 | cut -d, -f1 || echo "")
+
+# Timezone
+if [ -f /etc/timezone ]; then
+    TIMEZONE=$(cat /etc/timezone)
+elif [ -L /etc/localtime ]; then
+    TIMEZONE=$(readlink /etc/localtime | sed 's|.*/zoneinfo/||')
+else
+    TIMEZONE=""
+fi
+
+# Git config
+GIT_NAME=$(git config --global user.name 2>/dev/null || echo "")
+GIT_EMAIL=$(git config --global user.email 2>/dev/null || echo "")
+
+# GitHub CLI (if authenticated)
+if command -v gh &>/dev/null; then
+    GH_INFO=$(gh api user --jq '{login: .login, name: .name, blog: .blog, bio: .bio}' 2>/dev/null || echo "{}")
+else
+    GH_INFO="{}"
+fi
+
+# Code directories that exist
+CODE_DIRS=""
+for dir in ~/Repos ~/repos ~/Code ~/code ~/Projects ~/projects ~/Developer ~/dev ~/src; do
+    if [ -d "$dir" ]; then
+        CODE_DIRS="$CODE_DIRS\"$dir\","
+    fi
+done
+CODE_DIRS="[${CODE_DIRS%,}]"
+
+# Output as JSON
+cat <<EOF
+{
+  "username": "$USERNAME",
+  "fullName": "$FULLNAME",
+  "timezone": "$TIMEZONE",
+  "git": {
+    "name": "$GIT_NAME",
+    "email": "$GIT_EMAIL"
+  },
+  "github": $GH_INFO,
+  "codeDirs": $CODE_DIRS
+}
+EOF

package/bin/index-conversations.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Index conversations incrementally
+ *
+ * Called by hooks at session end / after compact to keep the conversation index fresh.
+ */
+
+import { updateConversationIndex } from "../src/conversations.js";
+
+export async function main(
+  update: typeof updateConversationIndex = updateConversationIndex,
+): Promise<number> {
+  try {
+    const result = await update();
+    console.log(
+      `Indexed conversations: ${result.filesUpdated} updated, ${result.skipped} skipped, ${result.exchangeCount} total`,
+    );
+    return 0;
+  } catch (err) {
+    console.error("Failed to index conversations:", err);
+    return 1;
+  }
+}
+
+export function isRunAsMain(argv1: string | undefined, moduleUrl: string): boolean {
+  return Boolean(argv1) && moduleUrl === `file://${argv1}`;
+}
+
+/* v8 ignore next 3 -- entry-point glue: only runs when this file is the process
+   entry (node dist/bin/index-conversations.js), a subprocess vitest cannot
+   instrument. main() and isRunAsMain() are covered directly. */
+if (isRunAsMain(process.argv[1], import.meta.url)) {
+  void main().then((code) => process.exit(code));
+}

package/bin/macrodata-daemon.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Macrodata Local Daemon entry point.
+ *
+ * All logic lives in `src/daemon.ts` (importable and unit-tested). This file is
+ * a thin CLI wrapper so the compiled `dist/bin/macrodata-daemon.js` stays the
+ * spawn target for the plugin and hook script.
+ *
+ * Usage:
+ *   MACRODATA_ROOT=~/.config/macrodata node macrodata-daemon.js
+ *
+ * Environment:
+ *   MACRODATA_AGENT=opencode|claude  (default: auto-detect)
+ *   MACRODATA_ROOT=/path/to/state
+ */
+
+import { runDaemon } from "../src/daemon.js";
+
+export function isRunAsMain(argv1: string | undefined, moduleUrl: string): boolean {
+  return Boolean(argv1) && moduleUrl === `file://${argv1}`;
+}
+
+/* v8 ignore next 3 -- entry-point glue: only runs when this file is the process
+   entry (node dist/bin/macrodata-daemon.js), a subprocess vitest cannot
+   instrument. runDaemon() is covered directly in the daemon tests. */
+if (isRunAsMain(process.argv[1], import.meta.url)) {
+  runDaemon();
+}

package/bin/macrodata-hook.sh

@@ -0,0 +1,277 @@
+#!/bin/bash
+#
+# Macrodata Local Hook Script
+#
+# Usage:
+#   macrodata-hook.sh session-start    - Launch daemon if not running, inject context
+#   macrodata-hook.sh prompt-submit    - Check daemon, inject pending context
+#
+
+# Get the directory where this script lives
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# Resolve compiled daemon: alongside when run from dist/bin, else ../dist/bin.
+if [ -f "$SCRIPT_DIR/macrodata-daemon.js" ]; then
+    DAEMON="$SCRIPT_DIR/macrodata-daemon.js"
+else
+    DAEMON="$SCRIPT_DIR/../dist/bin/macrodata-daemon.js"
+fi
+
+# State directory (configurable via MACRODATA_ROOT, config file, or defaults to ~/.config/macrodata)
+DEFAULT_ROOT="$HOME/.config/macrodata"
+CONFIG_FILE="$DEFAULT_ROOT/config.json"
+if [ -n "$MACRODATA_ROOT" ]; then
+    STATE_ROOT="$MACRODATA_ROOT"
+elif [ -f "$CONFIG_FILE" ]; then
+    STATE_ROOT=$(jq -r '.root // empty' "$CONFIG_FILE" 2>/dev/null)
+    STATE_ROOT="${STATE_ROOT:-$DEFAULT_ROOT}"
+else
+    STATE_ROOT="$DEFAULT_ROOT"
+fi
+
+# Output locations (PID file now follows STATE_ROOT for testing isolation)
+PIDFILE="$STATE_ROOT/.daemon.pid"
+PENDING_CONTEXT="$STATE_ROOT/.pending-context"
+LOGFILE="$STATE_ROOT/.daemon.log"
+JOURNAL_DIR="$STATE_ROOT/journal"
+
+# State files
+IDENTITY="$STATE_ROOT/state/identity.md"
+TODAY="$STATE_ROOT/state/today.md"
+HUMAN="$STATE_ROOT/state/human.md"
+WORKSPACE="$STATE_ROOT/state/workspace.md"
+FLAGS="$STATE_ROOT/state/flags.md"
+
+# Per-section injection caps (bytes) — a backstop against runaway growth, not a
+# tight corset. State is bounded working memory; a file over cap is truncated here
+# with a marker. The skills keep files well under this; the cap only catches failures.
+CAP_IDENTITY=4000
+CAP_TODAY=4000
+CAP_HUMAN=4000
+CAP_WORKSPACE=4000
+CAP_FLAGS=4000
+
+is_daemon_running() {
+    if [ -f "$PIDFILE" ]; then
+        local pid=$(cat "$PIDFILE")
+        if kill -0 "$pid" 2>/dev/null; then
+            return 0
+        fi
+    fi
+    return 1
+}
+
+start_daemon() {
+    if is_daemon_running; then
+        return 0
+    fi
+
+    local NODE="node"
+    # Ensure state directory exists
+    mkdir -p "$STATE_ROOT"
+    # Start daemon in background, redirect output to log
+    # Note: daemon writes its own PID file, we don't write it here
+    MACRODATA_ROOT="$STATE_ROOT" nohup "$NODE" "$DAEMON" >> "$LOGFILE" 2>&1 &
+
+    # Wait briefly for daemon to write PID file (up to 2 seconds)
+    local attempts=0
+    while [ $attempts -lt 20 ]; do
+        sleep 0.1
+        if is_daemon_running; then
+            return 0
+        fi
+        attempts=$((attempts + 1))
+    done
+}
+
+signal_daemon_reload() {
+    if [ -f "$PIDFILE" ]; then
+        local pid=$(cat "$PIDFILE")
+        if kill -0 "$pid" 2>/dev/null; then
+            kill -HUP "$pid" 2>/dev/null
+        fi
+    fi
+}
+
+inject_pending_context() {
+    if [ -s "$PENDING_CONTEXT" ]; then
+        cat "$PENDING_CONTEXT"
+        : > "$PENDING_CONTEXT"  # Clear the file
+    fi
+}
+
+get_recent_journal() {
+    local count="${1:-5}"
+    
+    if [ ! -d "$JOURNAL_DIR" ]; then
+        return
+    fi
+    
+    # Get most recent journal files and extract entries
+    local entries=""
+    for file in $(ls -t "$JOURNAL_DIR"/*.jsonl 2>/dev/null | head -3); do
+        if [ -f "$file" ]; then
+            # Get last N entries from each file, format as "- [topic] content"
+            entries="$entries$(tail -n "$count" "$file" 2>/dev/null | jq -r '"\n- [\(.topic)] \(.content | split("\n")[0])"' 2>/dev/null)"
+        fi
+    done
+    
+    echo "$entries" | head -n "$count"
+}
+
+list_state_files() {
+    local files=""
+
+    # State files
+    if [ -d "$STATE_ROOT/state" ]; then
+        for f in "$STATE_ROOT/state"/*.md; do
+            [ -f "$f" ] && files="$files\n- state/$(basename "$f")"
+        done
+    fi
+
+    # Entity files (scan all subdirs dynamically)
+    if [ -d "$STATE_ROOT/entities" ]; then
+        for subdir in "$STATE_ROOT/entities"/*/; do
+            [ -d "$subdir" ] || continue
+            local subdir_name=$(basename "$subdir")
+            for f in "$subdir"*.md; do
+                [ -f "$f" ] && files="$files\n- entities/$subdir_name/$(basename "$f")"
+            done
+        done
+    fi
+
+    if [ -z "$files" ]; then
+        echo "_No files yet_"
+    else
+        echo -e "$files"
+    fi
+}
+
+get_usage() {
+    cat <<'USAGE'
+- **state/** files are always here but BOUNDED (a screenful each, hard-capped). Keep only what's live; move detail out.
+- **flags.md** is how things reach the user across sessions — one line + pointer. Surface, don't hoard.
+- **journal** (`log_journal`) is durable and retrievable via `search_memory`. Writing it down is remembering, not forgetting — put detail here.
+- **entities/** hold persistent per-project/topic notes (searchable). Eviction is expected: resolved/aging items leave state for the journal/entity, leaving a pointer.
+- Search before claiming ignorance. Full guide: `plugins/macrodata/USAGE.md`.
+USAGE
+}
+
+get_schedules() {
+    local reminders_dir="$STATE_ROOT/reminders"
+
+    if [ ! -d "$reminders_dir" ]; then
+        echo "_No active schedules_"
+        return
+    fi
+
+    local schedules=""
+    for f in "$reminders_dir"/*.json; do
+        [ -f "$f" ] || continue
+        local line=$(jq -r '"- \(.description) (\(.type): \(.expression))"' "$f" 2>/dev/null)
+        [ -n "$line" ] && schedules="$schedules$line\n"
+    done
+
+    if [ -z "$schedules" ]; then
+        echo "_No active schedules_"
+    else
+        echo -e "$schedules"
+    fi
+}
+
+cap_file() {
+    local file="$1" max="$2"
+    if [ ! -f "$file" ]; then echo "_Empty_"; return; fi
+    local size
+    size=$(wc -c < "$file" | tr -d ' ')
+    if [ "$size" -le "$max" ]; then
+        cat "$file"
+    else
+        head -c "$max" "$file" | sed -e '$ d'
+        printf '\n[…truncated: %s of %s bytes shown. This file is over its budget — compact it. Detail lives in the journal; use search_memory / get_recent_journal.]\n' "$max" "$size"
+    fi
+}
+
+inject_static_context() {
+    # For local plugin, we inject everything needed for a normal session
+    local CONTEXT_FILE="$STATE_ROOT/.claude-context.md"
+
+    # Build context content
+    local CONTEXT=""
+
+    # Check if this is first run (no identity file)
+    if [ ! -f "$IDENTITY" ]; then
+        # Detect user info to avoid multiple permission prompts during onboarding
+        local USER_INFO=$("$SCRIPT_DIR/detect-user.sh" 2>/dev/null || echo '{}')
+        
+        CONTEXT="<macrodata>
+<macrodata-first-run state-root=\"$STATE_ROOT\">
+Macrodata local memory is not yet configured. Run \`/onboarding\` to set up.
+</macrodata-first-run>
+
+<macrodata-detected-user>
+$USER_INFO
+</macrodata-detected-user>
+</macrodata>"
+    else
+        CONTEXT="<macrodata>
+<macrodata-flags>
+$([ -s "$FLAGS" ] && cap_file "$FLAGS" "$CAP_FLAGS" || echo "_No open flags_")
+</macrodata-flags>
+
+<macrodata-today>
+$(cap_file "$TODAY" "$CAP_TODAY")
+</macrodata-today>
+
+<macrodata-identity>
+$(cap_file "$IDENTITY" "$CAP_IDENTITY")
+</macrodata-identity>
+
+<macrodata-workspace>
+$(cap_file "$WORKSPACE" "$CAP_WORKSPACE")
+</macrodata-workspace>
+
+<macrodata-journal>
+$(get_recent_journal 3)
+</macrodata-journal>
+
+<macrodata-schedules>
+$(get_schedules)
+</macrodata-schedules>
+
+<macrodata-usage>
+$(get_usage)
+</macrodata-usage>
+
+<macrodata-files root=\"$STATE_ROOT\">
+$(list_state_files)
+</macrodata-files>
+</macrodata>"
+    fi
+
+    # Write to file for global CLAUDE.md reference
+    mkdir -p "$STATE_ROOT"
+    echo "$CONTEXT" > "$CONTEXT_FILE"
+
+    # Also output to stdout for session context
+    echo "$CONTEXT"
+}
+
+case "$1" in
+    session-start)
+        start_daemon
+        signal_daemon_reload
+        inject_static_context
+        ;;
+    prompt-submit)
+        # Restart daemon if dead
+        start_daemon
+        # Inject only the daemon's targeted deltas. The full context is injected
+        # once at session-start and stays in the cached prefix; re-dumping it here
+        # would bloat the running context every turn and defeat prompt caching.
+        inject_pending_context
+        ;;
+    *)
+        echo "Usage: $0 {session-start|prompt-submit}" >&2
+        exit 1
+        ;;
+esac

package/dist/bin/index-conversations.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { updateConversationIndex } from "../src/conversations.js";
+
+//#region bin/index-conversations.ts
+/**
+* Index conversations incrementally
+*
+* Called by hooks at session end / after compact to keep the conversation index fresh.
+*/
+async function main(update = updateConversationIndex) {
+	try {
+		const result = await update();
+		console.log(`Indexed conversations: ${result.filesUpdated} updated, ${result.skipped} skipped, ${result.exchangeCount} total`);
+		return 0;
+	} catch (err) {
+		console.error("Failed to index conversations:", err);
+		return 1;
+	}
+}
+function isRunAsMain(argv1, moduleUrl) {
+	return Boolean(argv1) && moduleUrl === `file://${argv1}`;
+}
+/* v8 ignore next 3 -- entry-point glue: only runs when this file is the process
+entry (node dist/bin/index-conversations.js), a subprocess vitest cannot
+instrument. main() and isRunAsMain() are covered directly. */
+if (isRunAsMain(process.argv[1], import.meta.url)) {
+	void main().then((code) => process.exit(code));
+}
+
+//#endregion
+export { isRunAsMain, main };