engrm 0.1.0 → 0.2.0

package/README.md

@@ -1,121 +1,262 @@
 # Engrm
 
-**Cross-device memory for AI coding agents** — powered by [Candengo Vector](https://www.candengo.com).
+**Cross-device memory for AI coding agents.** Every session remembers what you learned yesterday — on any machine, for every team member.
 
-Engrm captures observations from AI-assisted coding sessions (discoveries, bugfixes, decisions, patterns) and syncs them to Candengo Vector so they're available on any machine, in any future session.
-
-Built from scratch. Inspired by [claude-mem](https://github.com/thedotmack/claude-mem)'s approach to hooking into Claude Code — but designed around cross-device sync from day one, with Candengo Vector as the backend.
+```
+npx engrm init
+```
 
 ---
 
-## The Problem
+## What It Does
+
+Your AI agent forgets everything between sessions. Engrm fixes that.
+
+- **Captures automatically** — hooks into Claude Code to record discoveries, bugfixes, decisions, and patterns as you work
+- **Remembers across devices** — fix a bug on your laptop, continue on your desktop with full context
+- **Shares with your team** — one developer's hard-won insight becomes everyone's knowledge
+- **Works offline** — local SQLite is the source of truth; syncs when connected
+- **Guards your code** — Sentinel audits changes in real-time before they land
+
+## Quick Start
+
+### 1. Sign up
+
+Visit [engrm.dev](https://engrm.dev) and create an account.
 
-Our dev team works across multiple machines and projects (Candengo, Alchemy, AIMY). Every Claude Code session starts from zero — no memory of what was done yesterday, on another machine, or by another developer. The agent re-discovers the same patterns, hits the same gotchas, and asks the same questions that were already answered in a different session.
+### 2. Install
 
-## The Solution
+```bash
+npx engrm init
+```
+
+This opens your browser for authentication, writes config to `~/.engrm/`, and registers the MCP server + hooks in Claude Code. Takes about 30 seconds.
+
+**Alternative methods:**
+```bash
+# From a provisioning token (shown on engrm.dev after signup)
+npx engrm init --token=cmt_your_token
+
+# Self-hosted Candengo Vector
+npx engrm init --url=https://vector.internal.company.com
+
+# Manual setup (air-gapped environments)
+npx engrm init --manual
+```
 
-An MCP server + Claude Code hooks that:
+### 3. Use Claude Code normally
 
-1. **Capture observations automatically** from coding sessions via Claude Code hooks (`PostToolUse`, `Stop`)
-2. **Store locally** in SQLite (offline-first, always available)
-3. **Sync to Candengo Vector** for cross-device, cross-developer search (BGE-M3 hybrid dense+sparse, cross-encoder reranking)
-4. **Inject relevant context** on session start — so the agent picks up where you (or a teammate) left off, on any machine
+That's it. Engrm works in the background:
+
+- **Session start** — injects relevant project memory into context
+- **While you work** — captures observations from tool use (edits, writes, commands)
+- **Session end** — generates a session digest, syncs to cloud, shows summary
+
+```
+━━━ Engrm Session Summary ━━━
+
+📋 Request: Fix the OAuth redirect validation
+🔍 Investigated: redirect_uri handling in auth.py
+💡 Learned: scheme + host + port must all match registered URIs
+✅ Completed: Stricter redirect_uri validation (auth.py)
+
+🟢 Risk: Low (0.12)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 4. Check status
+
+```bash
+npx engrm status
+```
+
+```
+Engrm Status
+
+  User:        david
+  Email:       david@example.com
+  Device:      macbook-a1b2c3d4
+  Plan:        Pro ($15/mo)
+  Candengo:    https://www.candengo.com
+  MCP server:  registered
+  Hooks:       registered (6 hooks)
+
+  Observations:    1,247 active
+  By type:         change: 412, discovery: 289, bugfix: 187, ...
+  Sentinel:        enabled (advisory, 142/200 today)
+  Sync:            push 2m ago, pull 5m ago
+  Security:        3 findings (1 high, 2 medium)
+```
 
 ---
 
-## Architecture
-
-```
-Developer's Machine (any device)
-+---------------------------------------------+
-|  Claude Code                                 |
-|       | MCP (stdio)                          |
-|  +-----------------------------------+       |
-|  |  Engrm MCP Server                 |       |
-|  |  - Observation capture            |       |
-|  |  - Local SQLite + FTS5            |       |
-|  |  - Sync outbox queue              |       |
-|  |  - Secret scrubbing               |       |
-|  +--------------+--------------------+       |
-|                 | HTTPS (when available)      |
-+-----------------+----------------------------+
-                  |
-                  v
-+---------------------------------------------+
-|  Candengo Vector (self-hosted or cloud)      |
-|  - BGE-M3 hybrid dense+sparse search        |
-|  - Cross-encoder reranking                   |
-|  - Multi-tenant (site_id / namespace)        |
-+---------------------------------------------+
-```
-
-**Key principle**: SQLite is the source of truth. Always available, always fast. Candengo Vector is the sync target that enables cross-device search. If the remote is unreachable, everything still works locally.
+## How It Works
+
+```
+Claude Code session
+  │
+  ├─ SessionStart hook ──→ inject relevant memory into context
+  │
+  ├─ PreToolUse hook ────→ Sentinel audits Edit/Write (optional)
+  │
+  ├─ PostToolUse hook ───→ extract observations from tool results
+  │
+  ├─ PreCompact hook ────→ re-inject memory before context compression
+  │
+  ├─ ElicitationResult ──→ capture MCP form submissions
+  │
+  └─ Stop hook ──────────→ session digest + sync + summary
+        │
+        ▼
+  Local SQLite (FTS5 + sqlite-vec)
+        │
+        ▼ (sync every 30s)
+  Candengo Vector (cloud)
+        │
+        ▼
+  Available on all your devices + team members
+```
+
+### MCP Tools
+
+The MCP server exposes tools that Claude can call directly:
+
+| Tool | Purpose |
+|------|---------|
+| `search` | Find relevant observations from memory (hybrid FTS5 + vector) |
+| `timeline` | Chronological context around an observation |
+| `get_observations` | Fetch full details by ID |
+| `save_observation` | Manually save something worth remembering |
+| `install_pack` | Load a curated knowledge pack for your stack |
+
+### Observation Types
+
+| Type | What it captures |
+|------|-----------------|
+| `discovery` | Learning about existing systems or codebases |
+| `bugfix` | Something was broken, now fixed |
+| `decision` | Architectural or design choice with rationale |
+| `change` | Meaningful modification (feature, config, docs) |
+| `feature` | New capability or functionality |
+| `refactor` | Code restructured without behavior change |
+| `pattern` | Recurring issue or technique |
+| `digest` | Session summary (auto-generated) |
 
 ---
 
-## Getting Started
+## Features
 
-Sign up at [engrm.dev](https://engrm.dev), then run the install command shown on the page:
+### Hybrid Search
+Local FTS5 + sqlite-vec (all-MiniLM-L6-v2, 384 dims) combined with Candengo Vector's BGE-M3 semantic search. Results merged via Reciprocal Rank Fusion.
+
+### Sentinel — Real-Time Code Audit
+LLM-powered review of every Edit/Write before it executes. Catches security issues, anti-patterns, and drift from team decisions.
+
+```
+⚠️  Sentinel: SQL query uses string concatenation instead of parameterized query
+   Rule: sql-injection
+   (Advisory mode — change allowed)
+```
+
+5 built-in rule packs: `security`, `auth`, `api`, `react`, `database`.
 
 ```bash
-npx engrm init --token=cmt_your_token_here
+npx engrm sentinel init-rules        # Install all rule packs
+npx engrm sentinel rules             # List available packs
 ```
 
-That's it. The command provisions your account, writes config, registers the MCP server and hooks in Claude Code. Your next Claude Code session has memory.
+### Starter Packs
+Pre-loaded knowledge for your tech stack. Detected automatically on session start.
 
-**For teams**: Admin creates a team at [engrm.dev/team](https://engrm.dev/team), shares the invite link. Team members sign up via the link and are pre-configured for the shared namespace.
+Available: `typescript-patterns`, `nextjs-patterns`, `node-security`, `python-django`, `react-gotchas`, `api-best-practices`, `web-security`
 
-**Self-hosted**: Point at your own Candengo Vector instance:
 ```bash
-npx engrm init --url=https://vector.internal.company.com --token=cmt_...
+npx engrm install-pack typescript-patterns
 ```
 
+### Secret Scrubbing
+Multi-layer regex scanning for API keys, passwords, tokens, and credentials. Sensitive content is redacted before storage and sync. Custom patterns configurable in `~/.engrm/settings.json`.
+
+### Observation Lifecycle
+Observations age gracefully: **active** (30 days, full weight) → **aging** (0.7x search weight) → **archived** (compacted into digests) → **purged** (after 12 months). Pinned observations never age.
+
 ---
 
-## How It Hooks Into Claude Code
+## Pricing
+
+| | Free | Vibe | Pro | Team |
+|---|---|---|---|---|
+| **Price** | $0 | $9/mo | $15/mo | £19/seat/mo |
+| **Observations** | 5,000 | 25,000 | Unlimited | Unlimited |
+| **Devices** | 1 | 3 | Unlimited | Unlimited |
+| **Cloud sync** | ✓ | ✓ | ✓ | ✓ |
+| **Sentinel** | — | Advisory (50/day) | Advisory (200/day) | Blocking (unlimited) |
+| **Retention** | 30 days | 90 days | 1 year | Unlimited |
+| **Team namespace** | — | — | — | ✓ |
 
-Engrm integrates via two mechanisms:
+Sign up at [engrm.dev](https://engrm.dev).
 
-### MCP Server
-Registered in Claude Code's MCP config, exposes tools the agent can call:
-- `search` — find relevant observations from memory
-- `timeline` — chronological context around an observation
-- `get_observations` — fetch full details by ID
-- `save_observation` — manually save something worth remembering
+---
+
+## Self-Hosting
 
-### Claude Code Hooks
-Shell scripts triggered by Claude Code lifecycle events:
-- `PostToolUse` — extract observations from tool results (the main capture path)
-- `Stop` — generate session summary, flush sync queue
+Point Engrm at your own [Candengo Vector](https://www.candengo.com) instance:
+
+```bash
+npx engrm init --url=https://vector.internal.company.com --token=cmt_...
+```
 
-This is similar to how claude-mem hooks in, but our implementation is independent — no shared code, no fork relationship.
+Candengo Vector provides the backend: BGE-M3 hybrid search, multi-tenant namespaces, and team sync. See the [Candengo docs](https://www.candengo.com/docs) for deployment.
 
 ---
 
-## Status
+## Configuration
+
+### User config: `~/.engrm/settings.json`
+
+Created by `engrm init`. Contains API credentials, sync settings, search preferences, secret scrubbing patterns, and Sentinel configuration.
 
-**Building.** The product brief, technical spec, and implementation plan are complete. Implementation is starting with Phase 1: local MCP server with SQLite storage, observation capture, and secret scrubbing.
+### Project config: `.engrm.json` (optional)
+
+Place in your project root to override project identity for non-git projects:
+
+```json
+{
+  "project_id": "internal/design-system",
+  "name": "Design System"
+}
+```
+
+### Claude Code integration
+
+Engrm auto-registers in:
+- `~/.claude.json` — MCP server (`engrm`)
+- `~/.claude/settings.json` — 6 lifecycle hooks
 
 ---
 
-## Project Documents
+## Tech Stack
 
-| Document | Contents |
-|---|---|
-| [BRIEF.md](BRIEF.md) | Product brief, target users, revenue model |
-| [SPEC.md](SPEC.md) | Technical specification: schemas, MCP tools, sync engine, search pipeline |
-| [PLAN.md](PLAN.md) | Phased implementation plan with effort estimates |
-| [SWOT.md](SWOT.md) | Strengths, weaknesses, opportunities, threats |
-| [COMPETITIVE.md](COMPETITIVE.md) | Competitive landscape analysis |
-| [MARKET.md](MARKET.md) | Market research, pricing, growth projections |
-| [INFRASTRUCTURE.md](INFRASTRUCTURE.md) | Scaling roadmap, capacity planning |
+- **Runtime**: TypeScript, runs on Bun (dev) or Node.js 18+ (npm)
+- **Local storage**: SQLite via better-sqlite3, FTS5 full-text search, sqlite-vec for embeddings
+- **Embeddings**: all-MiniLM-L6-v2 via @xenova/transformers (384 dims, ~23MB)
+- **Remote backend**: Candengo Vector (BGE-M3, Qdrant, hybrid dense+sparse search)
+- **MCP**: @modelcontextprotocol/sdk (stdio transport)
+- **AI extraction**: @anthropic-ai/claude-agent-sdk (optional, for richer observations)
 
 ---
 
 ## License
 
-Functional Source License v1.1 (FSL-1.1-ALv2) — source-available, part of the [Fair Source](https://fair.io) movement. Free to use, modify, and self-host for any non-competing purpose. You cannot offer this as a competing hosted service. Each version converts to Apache 2.0 after 2 years. Sentinel (real-time AI audit) is a separate proprietary product. See [LICENSE](LICENSE) for details.
+**FSL-1.1-ALv2** (Functional Source License) — part of the [Fair Source](https://fair.io) movement.
+
+- Free to use, modify, and self-host
+- You cannot offer this as a competing hosted service
+- Each version converts to Apache 2.0 after 2 years
+- Sentinel is a separate proprietary product
+
+See [LICENSE](LICENSE) for full terms.
 
 ---
 
-Built by [Unimpossible Consultants](https://unimpossible.com) — the team behind Candengo, Alchemy, and AIMY.
+Built by [Unimpossible Consultants](https://unimpossible.com) — the team behind [Candengo](https://www.candengo.com), Alchemy, and AIMY.

package/bin/build.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+/**
+ * Build script — compiles TypeScript to Node.js-compatible JavaScript.
+ *
+ * Uses Bun's bundler to produce self-contained .js files that run on Node.js.
+ * Output goes to dist/ and is what gets published to npm.
+ */
+
+import { rmSync, mkdirSync, copyFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = join(__dirname, "..");
+const dist = join(root, "dist");
+
+// Clean
+rmSync(dist, { recursive: true, force: true });
+mkdirSync(dist, { recursive: true });
+mkdirSync(join(dist, "hooks"), { recursive: true });
+
+console.log("Building Engrm for Node.js...\n");
+
+// Build CLI + MCP server
+const mainResult = await Bun.build({
+  entrypoints: [
+    join(root, "src/cli.ts"),
+    join(root, "src/server.ts"),
+  ],
+  outdir: dist,
+  target: "node",
+  format: "esm",
+  external: [
+    "better-sqlite3",
+    "sqlite-vec",
+    "@xenova/transformers",
+    "@modelcontextprotocol/sdk",
+    "@anthropic-ai/claude-agent-sdk",
+  ],
+});
+
+if (!mainResult.success) {
+  console.error("Build failed (main):");
+  for (const msg of mainResult.logs) console.error(msg);
+  process.exit(1);
+}
+console.log("  dist/cli.js");
+console.log("  dist/server.js");
+
+// Build hooks
+const hookResult = await Bun.build({
+  entrypoints: [
+    join(root, "hooks/session-start.ts"),
+    join(root, "hooks/pre-compact.ts"),
+    join(root, "hooks/post-tool-use.ts"),
+    join(root, "hooks/stop.ts"),
+    join(root, "hooks/sentinel.ts"),
+    join(root, "hooks/elicitation-result.ts"),
+  ],
+  outdir: join(dist, "hooks"),
+  target: "node",
+  format: "esm",
+  external: [
+    "better-sqlite3",
+    "sqlite-vec",
+    "@xenova/transformers",
+    "@modelcontextprotocol/sdk",
+    "@anthropic-ai/claude-agent-sdk",
+  ],
+});
+
+if (!hookResult.success) {
+  console.error("Build failed (hooks):");
+  for (const msg of hookResult.logs) console.error(msg);
+  process.exit(1);
+}
+console.log("  dist/hooks/session-start.js");
+console.log("  dist/hooks/pre-compact.js");
+console.log("  dist/hooks/post-tool-use.js");
+console.log("  dist/hooks/stop.js");
+console.log("  dist/hooks/sentinel.js");
+console.log("  dist/hooks/elicitation-result.js");
+
+// Add Node.js shebang to CLI and hooks (strip any existing shebangs first)
+async function addShebang(filePath) {
+  const raw = await Bun.file(filePath).text();
+  const stripped = raw.replace(/^#!.*\n/gm, "");
+  writeFileSync(filePath, `#!/usr/bin/env node\n${stripped}`);
+}
+
+await addShebang(join(dist, "cli.js"));
+await addShebang(join(dist, "server.js"));
+for (const hook of ["session-start", "pre-compact", "post-tool-use", "stop", "sentinel", "elicitation-result"]) {
+  await addShebang(join(dist, "hooks", `${hook}.js`));
+}
+
+console.log("\nBuild complete.");

package/bin/engrm.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Engrm CLI entry point for npm/npx.
+ * Runs the pre-built dist/cli.js on Node.js — no Bun required.
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Import and run the built CLI
+await import(join(__dirname, "..", "dist", "cli.js"));