@hmanlab/memo 0.5.0

package/README.md

@@ -0,0 +1,110 @@
+# @hmanlab/memo
+
+Local-first MCP server for persistent, persona-aware memory across projects.
+
+`memo` ships two surfaces: an MCP server (33 tools) for AI clients like
+Claude Code, and a Node CLI (`hmanlab-memory`) for power users. Both
+share the same backend — the CLI is a thin wrapper, not a re-implementation.
+
+Everything lives under `~/.hmanlab/`: one root SQLite DB + a `personas/`
+directory of YAML files + one DB per registered project. No cloud, no
+account, no telemetry.
+
+## What's in the box (v1.0.0)
+
+### MCP tools (33)
+- **Persona (11):** `persona_list`, `persona_get`, `persona_create`,
+  `persona_update`, `persona_delete`, `persona_clone`,
+  `persona_reload`, `user_persona_get`, `user_persona_update`
+- **Project (7):** `project_register`, `project_list`, `project_get`,
+  `project_switch`, `get_active_project`, `project_archive`,
+  `project_unregister`
+- **Memory (12):** `memory_save`, `memory_get`, `memory_update`,
+  `memory_delete`, `memory_search`, `memory_semantic_search`,
+  `memory_recent`, `memory_supersede`, `memory_promote`,
+  `memory_promote_to_global`, `memory_archive`, `memory_hygiene`,
+  `memory_link`, `memory_related`
+- **Session (3):** `session_start`, `session_end`, `session_list`
+
+Full list with schemas: [`docs/USAGE.md`](./docs/USAGE.md).
+Architecture: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
+Changelog: [`CHANGELOG.md`](./CHANGELOG.md).
+
+## Setup (one-time, on the machine)
+
+### As part of hl-plugins (dev)
+```bash
+pnpm install
+pnpm --filter @hmanlab/memo build
+hl-plugins install memo
+```
+
+### Standalone (after publishing to npm)
+```bash
+pnpm install -g @hmanlab/memo
+hmanlab-memory init                  # ~1s
+hmanlab-memory mcp-config claude-code   # prints `claude mcp add hmanlab-memory -- ...`
+```
+
+The CLI auto-installs Bun if missing and registers the MCP bundle
+under `~/.local/share/hl-plugins/memo/`, then wires it into
+`~/.claude.json`.
+
+## CLI quickstart
+
+```bash
+hmanlab-memory init
+hmanlab-memory project register ~/projects/ftmo ftmo
+hmanlab-memory project switch ftmo
+hmanlab-memory memory save "FTMO daily loss limit is 5 percent" --category rules --importance 0.9
+hmanlab-memory memory search "FTMO daily loss"    # JSON output, pipe to jq
+hmanlab-memory memory hygiene all                 # structured report
+hmanlab-memory project export ftmo                 # → ~/hmanlab-exports/ftmo-<date>.zip
+hmanlab-memory project import ~/hmanlab-exports/ftmo-*.zip
+hmanlab-memory status
+```
+
+Full CLI reference: [`docs/USAGE.md`](./docs/USAGE.md).
+
+## On-disk layout
+
+```
+~/.hmanlab/
+├── config.yaml          # cwd_auto_detect, persona_filter_mode, decay knobs
+├── root.db              # user_persona, ai_personas, projects,
+│                        # global_memories (+ _fts + _edges), schema migrations
+├── personas/            # persona YAML files (built-in + user)
+│   ├── default.yaml
+│   ├── work.yaml        # parent: default
+│   ├── creative.yaml    # parent: default
+│   └── <user-defined>.yaml
+└── projects/<name>/
+    ├── project.yaml    # description, decay_policy, channels
+    └── hmanlab.db      # memories (+ _fts + _vec + _edges), sessions
+```
+
+YAML is the source of truth for personas. SQLite is the source of truth
+for everything else. `persona_reload` re-syncs the DB after a hand edit.
+
+## What's in each phase (6 phases shipped)
+
+- **Phase 01:** Root DB, persona CRUD, FastMCP skeleton, 3 starter personas
+- **Phase 02:** Per-project DB, register, switch, archive, unregister
+- **Phase 03:** Memory CRUD, FTS5 search, hybrid ranking (MVP)
+- **Phase 04:** Cross-DB search, cwd auto-detect, sessions
+- **Phase 05:** Decay engine, conflict detection, hygiene, promotion
+- **Phase 06:** Export/import (zip), CLI, memory graph, docs
+
+Full changelog: [`CHANGELOG.md`](./CHANGELOG.md).
+
+## Development
+
+```bash
+pnpm install                          # workspace setup (from monorepo root)
+pnpm --filter @hmanlab/memo build     # build MCP bundle + CLI
+bun test packages/plugin-memo/tests/  # 175 tests
+pnpm typecheck                        # green
+```
+
+The MCP server is built to a single Bun bundle at `dist/memo-mcp-server.js`.
+The CLI is built to `dist/cli.js` and exposed via `bin/hmanlab-memory.js`.

package/bin/hmanlab-memory.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// CLI entry point. Built artifact at packages/plugin-memo/dist/cli.js is what
+// `pnpm install` actually puts on PATH (see package.json bin field).
+//
+// Source CLI is in src/cli/main.ts; this file is the install path shim
+// so the CLI works even before the build step.
+
+import { run } from "../dist/cli.js"
+// Commander expects [executable, script-path, ...args]. Under node this is
+// already the shape. Under bun, argv[0] is the bun binary and argv[1] is the
+// script — also already correct. So we just pass argv through.
+run(process.argv)

package/claude/skill/memo/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: memo
+description: Use when the user wants persistent memory across projects, persona-aware AI behavior, or to manage hmanlab-memo (multi-persona, multi-project, local-first memory for AI coding assistants). Front-load keywords: memory, persona, project, save, recall, search, decay, conflict, SQLite, hmanlab-memo, persona-aware, multi-persona, hmanlab-memory.
+---
+
+# memo — hmanlab-memo (local-first MCP memory)
+
+The `memo` MCP server exposes 9 tools that give an AI coding assistant
+persistent, persona-aware memory on the user's machine. Everything lives under
+`~/.hmanlab/` (one root SQLite DB + a `personas/` directory of YAML files).
+No cloud, no account, no telemetry.
+
+This is the Phase 01 slice: persona + user-persona CRUD only. Projects,
+memories, embeddings, and hybrid search land in later phases.
+
+| Tool                  | What it does                                                |
+| --------------------- | ----------------------------------------------------------- |
+| `persona_list`        | List all personas (built-in + user)                         |
+| `persona_get`         | Read one persona (resolves `parent` chain)                  |
+| `persona_create`      | Write a new YAML persona + DB row                           |
+| `persona_update`      | Edit a persona, bump version                                |
+| `persona_delete`      | Soft-delete (archive) — YAML stays                          |
+| `persona_clone`       | Duplicate a persona as a starting point                     |
+| `persona_reload`      | Re-scan `~/.hmanlab/personas/` and resync the DB            |
+| `user_persona_get`    | Read the user's persona singleton                          |
+| `user_persona_update` | Edit the user's persona                                    |
+
+## Setup (one-time, on the machine)
+
+1. Install Bun: `curl -fsSL https://bun.sh/install | bash`
+2. Install the plugin via the `hl-plugins` CLI:
+   ```bash
+   hl-plugins install memo
+   ```
+3. Restart Claude Code. The 9 tools above appear under the `memo` MCP server.
+
+The CLI auto-installs Bun if missing and registers the MCP bundle under
+`~/.local/share/hl-plugins/memo/`, then wires it into `~/.claude.json`.
+
+## On-disk layout
+
+```
+~/.hmanlab/
+├── config.yaml          # paths + embedding defaults (phase-01 reads/writes subset)
+├── root.db              # WAL-mode SQLite: user_persona, ai_personas
+└── personas/
+    ├── default.yaml     # built-in (warm, balanced)
+    ├── work.yaml        # built-in (parent: default)
+    ├── creative.yaml    # built-in (parent: default)
+    └── <user-defined>.yaml
+```
+
+YAML is the source of truth. Editing a file on disk and calling `persona_reload`
+updates the DB to match. The starter pack is extracted only on first boot;
+existing YAMLs are never overwritten.
+
+## When to use these tools
+
+- **User asks to switch hats / "talk like X" / use a persona** → `persona_list`
+  to see options, `persona_get` to read the full prompt, then continue the
+  conversation as that persona.
+- **User asks to remember a preference** → `user_persona_update` with the
+  preference text.
+- **User asks to create / edit a persona** → `persona_create` or
+  `persona_update`.
+- **User edits a persona YAML directly** → `persona_reload` to make the DB
+  match.
+- **User wants to fork an existing persona** → `persona_clone`.