engrm 0.1.0

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "engrm": {
+      "type": "stdio",
+      "command": "/Users/david/.bun/bin/bun",
+      "args": ["run", "src/server.ts"]
+    }
+  }
+}

package/AUTH-DESIGN.md

@@ -0,0 +1,436 @@
+# Auth Design — Engrm
+
+**Status**: Approved (Devstral review: 2026-03-10)
+**Gates**: Phase 3 (Sync) — local features work without auth
+
+---
+
+## 1. Design Principles
+
+1. **One credential type for sync**: `cvk_` API key is the only credential the sync engine uses
+2. **Multiple ways to obtain it**: OAuth flow (interactive), device flow (headless), manual (CI/CD)
+3. **One config directory**: `~/.engrm/` — settings, auth, and database all in one place
+4. **Offline-first**: Auth failure pauses sync, never breaks local features
+
+---
+
+## 2. Auth Flows
+
+### Flow A: Interactive (Browser Callback)
+
+Default for developers with a desktop environment.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ engrm init                                        │
+│                                                          │
+│ 1. User runs: engrm init                         │
+│ 2. CLI starts localhost callback server on random port  │
+│ 3. CLI opens browser to:                                │
+│    https://candengo.com/connect/mem?                     │
+│      redirect_uri=http://localhost:{port}/callback       │
+│      &state={random}                                     │
+│ 4. User logs in (or creates account) on candengo.com    │
+│ 5. User clicks "Authorize Engrm"                 │
+│ 6. Candengo redirects to localhost callback:             │
+│    http://localhost:{port}/callback?code=ABC&state=XYZ   │
+│ 7. CLI exchanges code for credentials:                  │
+│    POST /v1/mem/provision { "code": "ABC" }             │
+│    → { api_key: "cvk_...", site_id, namespace, ... }    │
+│ 8. CLI writes ~/.engrm/settings.json             │
+│ 9. CLI prints: "✓ Connected as david@example.com"       │
+└─────────────────────────────────────────────────────────┘
+```
+
+The OAuth callback exchanges for a **permanent `cvk_` API key** — not a short-lived access token. This is the same credential type as the existing provisioning flow. The OAuth flow is simply a more convenient delivery mechanism.
+
+### Flow B: Device Code (Headless / SSH)
+
+Auto-detected when no browser can be launched, or via `--no-browser` flag. Implements RFC 8628 (OAuth 2.0 Device Authorization Grant).
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ engrm init --no-browser                           │
+│                                                          │
+│ 1. CLI requests device code:                            │
+│    POST /v1/auth/device/code                            │
+│    → { device_code, user_code: "XXXX-YYYY",            │
+│         verification_uri, interval: 5 }                  │
+│                                                          │
+│ 2. CLI prints:                                          │
+│    "Open this URL on any device:                        │
+│     https://candengo.com/connect/mem/device              │
+│     Enter code: XXXX-YYYY"                              │
+│                                                          │
+│ 3. User opens URL on phone/desktop browser              │
+│ 4. User logs in, enters code, clicks "Authorize"        │
+│ 5. CLI polls every 5 seconds:                           │
+│    POST /v1/auth/device/token { device_code }           │
+│    → 202 (pending) | 200 { api_key, site_id, ... }     │
+│ 6. On success: writes settings.json                     │
+│ 7. CLI prints: "✓ Connected as david@example.com"       │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Flow C: Provisioning Token (Web Signup)
+
+Existing SPEC flow — user signs up on candengo.com, copies a one-liner.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Web: engrm.dev                                    │
+│                                                          │
+│ 1. User signs up (email + password, or GitHub OAuth)    │
+│ 2. Page shows install command:                          │
+│    npx engrm init --token=cmt_abc123...          │
+│ 3. CLI exchanges provisioning token for credentials:    │
+│    POST /v1/mem/provision { "token": "cmt_..." }        │
+│    → { api_key: "cvk_...", site_id, namespace, ... }    │
+│ 4. CLI writes settings.json                             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Flow D: Manual / CI/CD
+
+For CI/CD pipelines, air-gapped environments, or self-hosted deployments.
+
+```bash
+# Environment variable (CI/CD)
+export ENGRM_TOKEN=cvk_...
+
+# Manual configuration
+engrm init --manual
+# Prompts for: endpoint, api_key, site_id, namespace, user_id
+
+# Self-hosted
+engrm init --url=https://vector.internal.company.com --token=cmt_...
+```
+
+The sync engine checks `ENGRM_TOKEN` env var before reading from settings.json. This allows CI/CD pipelines to use Engrm without writing config files.
+
+---
+
+## 3. Credential Types
+
+| Prefix | Type | Lifetime | Use Case |
+|--------|------|----------|----------|
+| `cvk_` | API key | Permanent (revocable) | All sync operations. The ONE credential type for API access. |
+| `cmt_` | Provisioning token | 1 hour, single-use | Web signup → exchange for `cvk_` key |
+| `cm_` | Access token | 1 hour | Future: MCP-native OAuth 2.1 (Phase 4) |
+| `cmr_` | Refresh token | 90 days sliding | Future: MCP-native OAuth 2.1 (Phase 4) |
+
+**Key decision**: For Phase 3, only `cvk_` and `cmt_` exist. The `cm_`/`cmr_` token pair is reserved for Phase 4 when MCP-native OAuth is implemented. This avoids maintaining two auth models simultaneously.
+
+---
+
+## 4. Token Storage
+
+### Primary: `~/.engrm/settings.json`
+
+The `cvk_` API key is stored in the existing settings file. No separate auth file needed.
+
+```json
+{
+  "candengo_url": "https://www.candengo.com",
+  "candengo_api_key": "cvk_...",
+  "site_id": "unimpossible",
+  "namespace": "dev-memory",
+  "user_id": "david",
+  "user_email": "david@example.com",
+  "device_id": "macbook-a1b2c3d4",
+  "teams": [
+    { "id": "team_abc123", "name": "Unimpossible", "namespace": "dev-memory" }
+  ],
+  "sync": { ... },
+  "search": { ... },
+  "scrubbing": { ... }
+}
+```
+
+### Secret Scrubber: `cvk_` Pattern
+
+The existing scrubber already catches `cvk_` keys (see SPEC §6). This prevents API keys from leaking into observations.
+
+### OS Keychain (Phase 4)
+
+When `cm_`/`cmr_` tokens are introduced in Phase 4:
+- Refresh token (`cmr_`) → OS keychain (macOS Keychain / libsecret / Windows Credential Manager)
+- Access token (`cm_`) → memory only (short-lived, not persisted)
+- Fallback to file storage with logged warning if keychain unavailable
+
+---
+
+## 5. Team Membership
+
+### Data Model
+
+`teams` is an **array** in both the auth response and settings.json. This supports multi-team membership from day one.
+
+```typescript
+interface TeamMembership {
+  id: string;        // "team_abc123"
+  name: string;      // "Unimpossible"
+  namespace: string; // "dev-memory"
+}
+```
+
+### Namespace Resolution
+
+When syncing:
+- Personal namespace: `{user_id}-personal` (always exists)
+- Team namespace: from `teams[].namespace` (requires explicit join)
+
+The `search` tool's `scope` parameter determines which namespaces to query:
+- `personal` → personal namespace only
+- `team` → team namespace(s) only
+- `all` → all namespaces (default)
+
+### Team Provisioning
+
+Teams are **not** auto-provisioned. Flow:
+
+1. **Personal namespace**: auto-provisioned on first auth (any flow)
+2. **Team namespace**: explicit create or join action
+   - Admin creates team at `engrm.dev/team`
+   - Members join via invite link: `engrm.dev/join/team_abc123`
+   - Or CLI: `engrm team join --code=INVITE_CODE`
+
+---
+
+## 6. Server-Side Requirements
+
+### Endpoints (Phase 3)
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/v1/mem/provision` | POST | Exchange `cmt_` token or OAuth code for `cvk_` API key |
+| `/v1/auth/device/code` | POST | Request device authorization code (RFC 8628) |
+| `/v1/auth/device/token` | POST | Poll for device authorization completion |
+| `/v1/auth/revoke` | POST | Revoke an API key by value |
+| `/v1/auth/keys` | GET | List active API keys for account (dashboard) |
+| `/v1/auth/keys` | DELETE | Revoke specific API key (dashboard) |
+
+### Web Pages
+
+| URL | Purpose |
+|-----|---------|
+| `engrm.dev` | Landing page + signup |
+| `candengo.com/connect/mem` | OAuth authorization page |
+| `candengo.com/connect/mem/device` | Device code entry page |
+| `engrm.dev/team` | Team creation (admin) |
+| `engrm.dev/join/{code}` | Team invite acceptance |
+| `engrm.dev/dashboard` | Key management, usage, team settings |
+
+### Database Tables (Server)
+
+```sql
+-- User accounts
+CREATE TABLE mem_accounts (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email           TEXT UNIQUE NOT NULL,
+    created_at      TIMESTAMPTZ DEFAULT now()
+);
+
+-- API keys (permanent, revocable)
+CREATE TABLE mem_api_keys (
+    key_hash        TEXT PRIMARY KEY,           -- SHA-256 of cvk_ key (never store plaintext)
+    key_prefix      TEXT NOT NULL,              -- First 8 chars for identification
+    account_id      UUID NOT NULL REFERENCES mem_accounts(id),
+    name            TEXT,                       -- "MacBook Pro", "CI Pipeline"
+    scopes          TEXT[] DEFAULT '{read,write}',  -- read, write, admin
+    created_at      TIMESTAMPTZ DEFAULT now(),
+    last_used_at    TIMESTAMPTZ,
+    revoked_at      TIMESTAMPTZ                -- NULL = active
+);
+
+-- Provisioning tokens (short-lived, single-use)
+CREATE TABLE mem_provision_tokens (
+    token           TEXT PRIMARY KEY,           -- cmt_abc123...
+    account_id      UUID NOT NULL REFERENCES mem_accounts(id),
+    expires_at      TIMESTAMPTZ NOT NULL,       -- created_at + 1 hour
+    used_at         TIMESTAMPTZ,               -- NULL until redeemed
+    created_at      TIMESTAMPTZ DEFAULT now()
+);
+
+-- Device authorization codes (RFC 8628)
+CREATE TABLE mem_device_codes (
+    device_code     TEXT PRIMARY KEY,
+    user_code       TEXT UNIQUE NOT NULL,       -- XXXX-YYYY (human-readable)
+    account_id      UUID,                       -- NULL until user authorizes
+    expires_at      TIMESTAMPTZ NOT NULL,       -- created_at + 15 minutes
+    authorized_at   TIMESTAMPTZ,               -- NULL until authorized
+    created_at      TIMESTAMPTZ DEFAULT now()
+);
+
+-- Team membership
+CREATE TABLE mem_teams (
+    id              TEXT PRIMARY KEY,           -- team_abc123
+    name            TEXT NOT NULL,
+    namespace       TEXT NOT NULL,
+    owner_id        UUID NOT NULL REFERENCES mem_accounts(id),
+    created_at      TIMESTAMPTZ DEFAULT now()
+);
+
+CREATE TABLE mem_team_members (
+    team_id         TEXT NOT NULL REFERENCES mem_teams(id),
+    account_id      UUID NOT NULL REFERENCES mem_accounts(id),
+    role            TEXT DEFAULT 'member',      -- owner, admin, member
+    joined_at       TIMESTAMPTZ DEFAULT now(),
+    PRIMARY KEY (team_id, account_id)
+);
+```
+
+---
+
+## 7. Token Scopes
+
+| Scope | Allows | Use Case |
+|-------|--------|----------|
+| `read` | search, get_observations, timeline, session_context | Read-only sync, CI/CD consumers |
+| `write` | save_observation, pin_observation + all `read` | Normal agent usage |
+| `admin` | team management, key revocation + all `write` | Team admins |
+
+Default scopes for new keys: `read, write`.
+CI/CD keys should be created with `read` only to limit blast radius.
+
+---
+
+## 8. Sync Engine Auth Integration
+
+```typescript
+// src/sync/auth.ts
+
+/**
+ * Get a valid API key for sync operations.
+ * Priority: env var → settings.json
+ */
+export function getApiKey(config: Config): string | null {
+  // CI/CD: environment variable takes precedence
+  const envKey = process.env.ENGRM_TOKEN;
+  if (envKey && envKey.startsWith("cvk_")) return envKey;
+
+  // Interactive: from settings
+  if (config.candengo_api_key && config.candengo_api_key.startsWith("cvk_")) {
+    return config.candengo_api_key;
+  }
+
+  return null;
+}
+
+/**
+ * Check if sync is configured and authenticated.
+ */
+export function isSyncReady(config: Config): boolean {
+  return getApiKey(config) !== null && config.candengo_url !== "";
+}
+```
+
+### Auth Failure Handling
+
+When the sync engine gets a 401 from the API:
+1. Set sync state to `paused_auth`
+2. Log: "Sync paused: API key invalid or revoked. Run 'engrm init' to re-authenticate."
+3. Surface warning in next MCP tool response via `_meta.warning` field
+4. Do not retry sync until user re-authenticates
+5. Local features continue working normally
+
+---
+
+## 9. Token Revocation
+
+### API Key Rotation
+
+Users can rotate keys from the dashboard (`engrm.dev/dashboard`) or CLI:
+
+```bash
+engrm auth rotate
+# 1. Creates new cvk_ key on server
+# 2. Updates settings.json with new key
+# 3. Revokes old key
+```
+
+### Revocation Scenarios
+
+| Scenario | Action |
+|----------|--------|
+| User runs `engrm auth revoke` | Revoke current key, clear from settings |
+| Lost/stolen device | Revoke key from web dashboard |
+| Team member removed | Admin revokes member's team-scoped keys |
+| Account deletion | All keys revoked server-side |
+| Suspected compromise | `engrm auth rotate` (atomic: new key, then revoke old) |
+
+### Server-Side
+
+- Keys are stored as SHA-256 hashes (never plaintext)
+- `key_prefix` (first 8 chars) allows identification in dashboard without exposing full key
+- `last_used_at` updated on each API call for activity monitoring
+- Revoked keys return 401 immediately
+
+---
+
+## 10. Cross-Agent Compatibility
+
+| Agent | Init Flow | Runtime Auth |
+|-------|-----------|--------------|
+| Claude Code | `engrm init` (any flow) | MCP server reads `cvk_` from settings.json |
+| Codex CLI | Same init + set `bearer_token_env_var` | Codex passes token via env var |
+| Cursor | Same init | MCP server reads from settings.json |
+| Windsurf | Same init | MCP server reads from settings.json |
+| Cline | Same init | MCP server reads from settings.json |
+| CI/CD | `ENGRM_TOKEN=cvk_...` | Sync engine reads env var |
+
+All agents share the same `cvk_` API key and the same settings.json. The MCP server binary is identical across agents — agent detection is separate from auth.
+
+---
+
+## 11. Phase 4: MCP-Native OAuth 2.1
+
+When the MCP OAuth 2.1 spec stabilises and agents implement it:
+
+1. MCP server returns `401 Unauthorized` with `WWW-Authenticate` header
+2. Agent handles browser flow automatically (no `engrm init` needed)
+3. Server issues short-lived `cm_` access token + `cmr_` refresh token
+4. Refresh token stored in OS keychain via `keytar` or equivalent
+5. Access token refreshed automatically by MCP client
+6. This becomes the **preferred** flow; `cvk_` keys remain for CI/CD and backwards compat
+
+This is additive — Track A (`cvk_` keys) continues to work. Track B (MCP OAuth) is an optional upgrade path.
+
+---
+
+## 12. Implementation Timeline
+
+| Phase | Auth Work | Depends On |
+|-------|-----------|------------|
+| Phase 2 (current) | No auth needed — local only | — |
+| Phase 3 (Sync) | Implement Flows A-D, `cvk_` key auth, revocation endpoints, team model | Candengo web backend |
+| Phase 3.5 | Web dashboard (key management, team admin) | Phase 3 |
+| Phase 4 | MCP-native OAuth 2.1, keychain storage, `cm_`/`cmr_` tokens | MCP spec stabilisation |
+
+### Phase 3 Implementation Order
+
+1. `POST /v1/mem/provision` — exchange `cmt_` token for `cvk_` key (server)
+2. `engrm init --token=cmt_...` — CLI provisioning (client)
+3. `engrm init` — browser OAuth callback flow (client)
+4. `engrm init --no-browser` — device code flow (client + server)
+5. `ENGRM_TOKEN` env var support in sync engine (client)
+6. `POST /v1/auth/revoke` — key revocation (server)
+7. `engrm auth rotate` — key rotation (client)
+8. Team endpoints + `engrm team join` (client + server)
+
+---
+
+## Decisions Log
+
+| # | Decision | Rationale | Review |
+|---|----------|-----------|--------|
+| 1 | `cvk_` API key is the single credential for sync | Avoids two auth models, two validation paths. OAuth is delivery, not credential type. | Devstral: approved |
+| 2 | All config in `~/.engrm/` | Consolidate — no split between `~/.config/` and `~/.engrm/` | Devstral: approved |
+| 3 | Device flow (RFC 8628) for headless/SSH | Localhost callback fails for remote dev. Device flow works everywhere. | Devstral: required |
+| 4 | `teams` is an array, not scalar | Multi-team membership from day one. Cheap now, expensive to migrate later. | Devstral: required |
+| 5 | Personal namespace auto-provisioned, team explicit | Prevents orphaned team namespaces from solo signups | Devstral: approved |
+| 6 | Token revocation is Phase 3 blocker | Basic security requirement — cannot ship sync without revocation | Devstral: required |
+| 7 | MCP-native OAuth deferred to Phase 4 | Spec still stabilising, no agent fully implements it | Devstral: approved |
+| 8 | API keys stored as SHA-256 hashes server-side | Standard practice — never store plaintext credentials | Devstral: approved |
+| 9 | `ENGRM_TOKEN` env var for CI/CD | Pipelines need stable credentials without config files | Devstral: approved |
+| 10 | Scopes: read, write, admin | Limits blast radius of CI/CD tokens and leaked keys | Devstral: approved |

package/BRIEF.md

@@ -0,0 +1,197 @@
+# Engrm — Product Brief
+
+## Executive Summary
+
+Engrm is a **cross-device, team-shared memory layer for AI coding agents** — built on Candengo Vector's proven RAG infrastructure. It captures what developers learn, discover, fix, and decide during AI-assisted coding sessions and makes that knowledge instantly available across all their devices, team members, and future sessions.
+
+**We're building this to solve our own problem first.** 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 team member. Engrm fixes this with offline-first local storage that syncs to Candengo Vector, giving every developer's AI agent shared project context from day one.
+
+The first integration targets **Claude Code** via its MCP and hooks system. The MCP interface is agent-agnostic, so future agents that support MCP can use the same memory backend.
+
+**Not a fork.** Built from scratch, inspired by claude-mem's approach to Claude Code integration. No shared code, no AGPL dependency. Clean-room implementation designed around cross-device sync and team memory from the start.
+
+**Built by Unimpossible Consultants** — the team behind the Candengo AI Knowledge Infrastructure platform, Alchemy, and AIMY.
+
+---
+
+## The Problem
+
+### Context Amnesia
+Every new Claude Code session starts from zero. Yesterday's debugging insights, architectural decisions, and hard-won knowledge are gone.
+
+### Multi-Device Friction
+Fix a bug on the laptop, continue on the desktop — no shared context. Our developers work across 2-3 machines and constantly re-explain the same codebase to the agent.
+
+### Team Knowledge Silos
+Developer A discovers a critical gotcha on Monday. Developer B hits the same issue on Tuesday. There's no automatic knowledge transfer between team members' AI agents. New team members' agents have zero institutional knowledge.
+
+### Wasted Tokens and Time
+AI agents re-discover the same patterns, make the same mistakes, ask the same clarifying questions — session after session, developer after developer.
+
+### No Cross-Device Team Solution Exists
+- claude-mem: local SQLite + ChromaDB, single device only
+- mem0: cloud-only SaaS, no self-hosted option
+- Cognee: knowledge graphs, no agent memory focus
+- IDE memory (Cursor, Windsurf): locked to one tool
+
+None offer offline-first cross-device sync with team memory on self-hosted infrastructure.
+
+---
+
+## The Solution
+
+### Core Product
+An MCP server + Claude Code hooks that:
+1. **Self-provisions in under 2 minutes** — sign up at engrm.dev, run one command, done
+2. **Captures observations automatically** from coding sessions (bugfixes, discoveries, decisions, patterns)
+3. **Stores locally** in SQLite (instant, always works, offline-first)
+4. **Syncs to Candengo Vector** when connected (cross-device search, semantic retrieval)
+5. **Injects relevant context** on session start — agent picks up where you (or a teammate) left off, on any machine
+6. **Scrubs secrets** before storage (API keys, tokens, passwords, connection strings)
+
+### Architecture
+
+```
+Developer's Machine (any device)
+┌─────────────────────────────────────────────┐
+│  Claude Code / Future MCP Agent             │
+│       ↕ MCP (stdio)                         │
+│  ┌───────────────────────────────────┐      │
+│  │  Engrm MCP Server          │      │
+│  │  - Observation capture (hooks)    │      │
+│  │  - Local SQLite + FTS5            │      │
+│  │  - Sync outbox queue              │      │
+│  │  - Secret scrubbing               │      │
+│  └──────────────┬────────────────────┘      │
+│                 │ HTTPS (when available)     │
+└─────────────────┼───────────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────────┐
+│  Candengo Vector (self-hosted or cloud)     │
+│  - BGE-M3 hybrid dense+sparse search       │
+│  - Cross-encoder reranking                  │
+│  - Multi-tenant (site_id/namespace)         │
+└─────────────────────────────────────────────┘
+```
+
+### Data Flow
+
+```
+1. Developer works with Claude Code
+2. Agent uses tools (reads files, runs commands, edits code)
+3. PostToolUse hook → observation extracted (title, narrative, facts, type)
+4. Secret scrubber strips sensitive content
+5. Observation saved to local SQLite (instant, always works)
+6. Observation added to sync_outbox
+7. Sync engine pushes to Candengo Vector (fire-and-forget)
+   - Online → pushed immediately
+   - Offline → stays in outbox, retried on timer
+8. Next session (any device) → search hits both local + Candengo Vector
+9. Agent has context from previous sessions
+```
+
+---
+
+## Target Users
+
+### Phase 1: Our Team (Dogfood)
+- Unimpossible dev team working across multiple machines and projects (Candengo, Alchemy, AIMY)
+- Shared project memory so every developer's agent has team context
+- Self-hosted on our own Candengo Vector infrastructure
+
+### Phase 2: Individual Developers (Solo Plan)
+- Power users who want persistent AI memory without cloud lock-in
+- Privacy-conscious developers who want self-hosted infrastructure
+
+### Phase 3: External Teams (Team Plan)
+- Small-to-medium dev teams wanting shared institutional knowledge
+- New team member's AI agent instantly has access to team knowledge
+
+### Phase 4: Enterprise
+- Large engineering organisations
+- Compliance-sensitive environments requiring self-hosted data
+
+---
+
+## Key Differentiators
+
+| Feature | Engrm | claude-mem | mem0 |
+|---|---|---|---|
+| Free cloud sync | Yes (generous free tier) | No (local only) | 10K memories free |
+| Cross-device sync | Yes (offline-first) | No (local only) | Cloud only |
+| Self-hosted option | Yes (Candengo Vector) | Local only | No (SaaS) |
+| Offline-first | Yes (SQLite + outbox) | N/A (always local) | No |
+| Team memory | Yes (shared namespace) | No | Limited |
+| Multi-agent support | MCP standard | Claude Code only | Multiple (via API) |
+| Vector search quality | BGE-M3 hybrid + reranking | ChromaDB default | Proprietary |
+| Secret scrubbing | Yes | No | Unknown |
+| License | FSL-1.1-ALv2 (source-available, Fair Source) | AGPL-3.0 | Proprietary |
+
+---
+
+## Licensing Strategy
+
+**Split model** — core client published, premium features proprietary:
+
+| Component | License | Published? |
+|-----------|---------|-----------|
+| Core client (MCP server, hooks, SQLite, search, sync) | FSL-1.1-ALv2 | Yes (GitHub) |
+| Sentinel (real-time AI audit, config push, team standards) | Proprietary | No (private repo) |
+| Server (Candengo Vector) | Proprietary | No (private repo) |
+
+**FSL-1.1-ALv2 (Functional Source License)** — part of the [Fair Source](https://fair.io) movement. Used by Sentry, Codecov, GitButler, Keygen.
+
+What it allows:
+- Developers can read, modify, and run the code freely
+- Companies can use it internally without restriction
+- Each version automatically converts to Apache 2.0 after 2 years
+
+What it restricts:
+- Nobody can fork it and offer a competing hosted service
+
+**Why not MIT/Apache**: Too permissive. A competitor could fork the plugin and offer a competing hosted service.
+
+**Why not AGPL**: Too restrictive for adoption. Many companies have blanket AGPL bans.
+
+**Why not ELv2**: FSL is better — the 2-year Apache 2.0 conversion is a trust signal, and FSL has growing ecosystem legitimacy via Fair Source.
+
+**Why separate Sentinel**: Premium IP (audit LLM orchestration, team standards sync, dashboard config push) stays in a private repo. This is the GitLab CE/EE pattern — clean separation, no license gymnastics.
+
+---
+
+## Revenue Model
+
+### Free-First, Upgrade for More
+
+The free tier is the product, not a demo. Developers get real cross-device sync with generous limits. Paid tiers unlock more storage, more devices, and team features.
+
+| Tier | Price | Includes | Target |
+|---|---|---|---|
+| **Free** | $0 | Cloud sync, 10K observations, 2 devices, 1 user | Individual devs getting started |
+| **Solo** | $9/mo | 50K observations, unlimited devices, priority sync | Power users, multi-machine devs |
+| **Pro** | $19/mo | Unlimited observations, unlimited devices, advanced search | Heavy users |
+| **Team** | $12/seat/mo (min 3) | Shared team memory, team analytics, admin controls | Dev teams (2-20) |
+| **Enterprise** | Custom | Self-hosted Candengo Vector + support SLA, SSO, audit | Large orgs, compliance |
+
+**Free tier rationale**: 10K observations is roughly 2-3 months of active daily use for a solo developer. Long enough to get hooked, natural upgrade when they hit the limit. Two devices covers laptop + desktop — the core cross-device use case.
+
+**Self-hosted is always free**: Anyone can run their own Candengo Vector instance. The paid tiers are for the convenience of our hosted infrastructure.
+
+### Revenue Flywheel
+```
+Free users (adoption) → Hit limits → Upgrade to Solo/Pro
+  → Tell teammates → Team plan → Enterprise interest
+  → More users → Justifies infrastructure investment → Better service → ...
+```
+
+---
+
+## Success Metrics
+
+| Metric | Target (6 months) | Target (12 months) |
+|---|---|---|
+| GitHub stars (plugin) | 1,000 | 10,000 |
+| Active installations | 500 | 5,000 |
+| Candengo Vector signups via Mem | 100 | 1,000 |
+| Cross-device sync events/day | 10,000 | 100,000 |

package/CLAUDE.md

@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+## Project Overview
+
+Engrm (engrm.dev) is a cross-device, team-shared memory layer for AI coding agents. Built to let our dev team share project context across machines and developers. It captures observations (discoveries, bugfixes, decisions, patterns) from AI-assisted coding sessions and syncs them via Candengo Vector.
+
+**Not a fork.** Built from scratch, inspired by claude-mem's approach to hooking into Claude Code. No shared code, no AGPL dependency.
+
+**Branding**: Public-facing product name is "Engrm" (engrm.dev). Repo stays `candengo-mem`. Server-side internals stay `mem_*`. MCP server name is "engrm". Config dir is `~/.engrm/`. Env var is `ENGRM_TOKEN`.
+
+## Key Documents
+
+- `BRIEF.md` — Product brief, architecture, revenue model, success metrics
+- `SWOT.md` — Strengths, weaknesses, opportunities, threats analysis
+- `PLAN.md` — Phased implementation plan with component architecture and effort estimates
+- `SPEC.md` — Technical specification: schemas, MCP tools, sync engine, search pipeline
+- `COMPETITIVE.md` — Competitive analysis vs claude-mem, mem0, Cognee, etc.
+- `MARKET.md` — Market research, competitor pricing, influencer reach, growth projections
+- `INFRASTRUCTURE.md` — Scaling roadmap, account-based routing, capacity planning, cost analysis
+- `AUTH-DESIGN.md` — Authentication flows, credential types, team model, token revocation
+- `SYNC-ARCHITECTURE.md` — Bidirectional sync protocol, change feed, multi-agent compatibility
+- `SERVER-API-PLAN.md` — Server-side API plan: sync, teams, billing, usage (Devstral-reviewed)
+- `SENTINEL.md` — Sentinel: real-time AI audit for coding agents (competitive research, architecture, implementation plan)
+
+## Technology Stack
+
+- **MCP Server**: TypeScript + Bun, MCP SDK (stdio transport)
+- **Local Storage**: SQLite (bun:sqlite) with FTS5 for offline search
+- **Remote Backend**: Candengo Vector (BGE-M3, Qdrant, hybrid search)
+- **Agent Support**: Claude Code (hooks + MCP), future MCP-compatible agents
+
+## Architecture
+
+```
+Agent ↔ MCP Server ↔ Local SQLite ↔ Sync Engine ↔ Candengo Vector
+```
+
+- SQLite is the source of truth (always available, offline-first)
+- Sync outbox queues observations for push to Candengo Vector
+- Search combines local FTS5 + remote vector search with result merging
+
+## Development
+
+This project is in early development. See `PLAN.md` for implementation phases and `SPEC.md` for technical details.