engrm 0.1.0 → 0.2.1

package/INFRASTRUCTURE.md

@@ -1,252 +0,0 @@
-# Infrastructure & Scaling — Engrm
-
-## Zero-Cost Start
-
-Day one, Engrm runs on your **existing Candengo Vector server**. The memory namespace is just additional data in the same Qdrant instance. No new infrastructure needed.
-
-| Stage | Users | Extra Cost | What Changes |
-|---|---|---|---|
-| Day 1 | You + team (2-5) | **$0** | Memory namespace added to existing Candengo Vector |
-| Launch | 100-500 | **$0** | Same server, barely noticeable load |
-| Traction | 500-5K | **$0-30** | Maybe bump RAM on existing server |
-| Growth | 5K-30K | **~$200** | Dedicated GEX44 or equivalent |
-| Scale | 30K-100K | **~$416** | Split GPU + Qdrant servers |
-| Big | 100K-300K | **~$650-975** | Sharded Qdrant |
-
-You don't spend real money until you have a problem worth having.
-
----
-
-## Account-Based Routing
-
-### The Pattern
-
-Every user account is assigned to a backend server. The plugin talks to one endpoint forever. A simple lookup routes to the right backend.
-
-```
-Plugin → mem.candengo.com → Router (api_key lookup) → Backend server
-```
-
-That's it. A dictionary lookup. No Kubernetes, no auto-scaling groups, no service mesh.
-
-### Schema
-
-```sql
--- Accounts
-CREATE TABLE mem_accounts (
-    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    user_id     TEXT UNIQUE NOT NULL,
-    api_key     TEXT UNIQUE NOT NULL,       -- cvk_...
-    email       TEXT,
-    backend_id  TEXT NOT NULL,              -- "eu-1"
-    namespace   TEXT NOT NULL,              -- their memory namespace
-    site_id     TEXT NOT NULL,              -- their tenant
-    tier        TEXT DEFAULT 'free',        -- free | solo | pro | team
-    status      TEXT DEFAULT 'active',      -- active | migrating | suspended
-    created_at  TIMESTAMPTZ DEFAULT now()
-);
-
--- Backends
-CREATE TABLE mem_backends (
-    backend_id  TEXT PRIMARY KEY,           -- "eu-1"
-    url         TEXT NOT NULL,              -- "https://vec-eu-1.candengo.com"
-    region      TEXT DEFAULT 'eu',
-    capacity_pct FLOAT DEFAULT 0,           -- auto-updated from /metrics
-    max_users   INTEGER DEFAULT 30000,
-    status      TEXT DEFAULT 'active',      -- active | draining | full
-    created_at  TIMESTAMPTZ DEFAULT now()
-);
-
-CREATE INDEX idx_accounts_api_key ON mem_accounts(api_key);
-CREATE INDEX idx_accounts_backend ON mem_accounts(backend_id);
-```
-
-### Plugin Config Flow
-
-From the user's perspective, setup starts at `www.engrm.dev`:
-
-```
-1. Developer visits www.engrm.dev
-2. Signs up (email + password, or GitHub OAuth)
-3. Backend creates account, namespace, provisioning token
-4. Page shows personalised install command:
-   npx engrm init --token=cmt_abc123...
-5. Developer runs command in terminal
-6. Plugin calls POST /v1/mem/provision with token
-7. API returns:
-   {
-     "endpoint": "https://mem.candengo.com",  ← always the same
-     "api_key": "cvk_...",
-     "site_id": "...",
-     "namespace": "dev-memory-david"
-   }
-8. Plugin writes settings.json, registers MCP + hooks in Claude Code
-9. Ready — next Claude Code session has memory
-```
-
-The provisioning token is short-lived (1 hour) and single-use — the permanent API key never appears in the browser or clipboard. The plugin never knows which backend it's on. The endpoint never changes.
-
-For teams: admin creates team at `www.engrm.dev/team`, shares invite URL. Team members sign up via the invite, their account is pre-configured for the shared team namespace.
-
-### Router
-
-The router is a thin proxy. On each request:
-
-```
-1. Extract api_key from header
-2. Lookup in mem_accounts → get backend_id
-3. Lookup in mem_backends → get url
-4. Proxy request to url
-5. Return response
-```
-
-Cache the api_key → url mapping in Redis or in-memory (TTL 5 minutes). The lookup adds <1ms latency.
-
-**Day 1 implementation**: No router needed. Plugin talks directly to your existing Candengo Vector. Add the router when you need a second backend.
-
-**Day 1+ implementation**: Traefik with header-based routing rules. One afternoon of work.
-
-**Later**: Replace with account-aware FastAPI proxy when you need per-user routing and migration support.
-
----
-
-## Adding a New Server
-
-Zero downtime. No user impact.
-
-```
-Step 1: Spin up new Candengo Vector instance
-        → docker-compose up on new server
-        → Configure BGE-M3, Qdrant, API
-
-Step 2: Register in backends table
-        INSERT INTO mem_backends (backend_id, url, region, status)
-        VALUES ('eu-2', 'https://vec-eu-2.candengo.com', 'eu', 'active');
-
-Step 3: New signups automatically route to eu-2 (lowest capacity)
-        Existing users stay on eu-1 (no migration)
-
-Step 4: Done. 10 minutes of work.
-```
-
-### User Migration (rebalancing)
-
-If a server gets too hot or you're decommissioning hardware:
-
-```
-Step 1: Mark user as migrating
-        UPDATE mem_accounts SET status = 'migrating' WHERE user_id = 'X';
-
-Step 2: Background job exports from old backend
-        GET /v1/documents?namespace=user-namespace → all their data
-
-Step 3: Bulk ingest to new backend
-        POST /v1/ingest/batch on new server
-
-Step 4: Flip the pointer
-        UPDATE mem_accounts SET backend_id = 'eu-2', status = 'active'
-        WHERE user_id = 'X';
-
-Step 5: Next request routes to new server automatically
-
-Step 6: Clean up old data at leisure
-```
-
-The user's plugin never reconfigures. Same API key. Same endpoint. They don't even know it happened.
-
----
-
-## Capacity Planning
-
-### Per-User Resource Profile
-
-| Metric | Value |
-|---|---|
-| Observations per active user/week | ~75 |
-| Vectors generated per active user/month | ~325 |
-| Storage per vector (quantised + metadata) | ~2.1 KB RAM + 4.8 KB disk |
-| RAM per active user (month 6 steady state) | ~3.5 MB |
-| Monthly active rate | ~30% of total users |
-
-### Server Capacity
-
-Using Hetzner GEX44 (EUR 184/month, 64GB RAM, RTX 4000 Ada, 2x 1.92TB NVMe):
-
-| Metric | Capacity |
-|---|---|
-| Usable RAM for Qdrant (with quantisation) | ~50 GB |
-| Max vectors in RAM | ~25M |
-| Max users (at month 6 steady state) | ~30K |
-| Peak QPS supported | ~50 |
-| Embedding throughput | ~150-250/sec |
-| GPU utilisation at 30K users | ~15% |
-
-### Scaling Triggers
-
-| Trigger | Threshold | Action |
-|---|---|---|
-| RAM usage > 70% | ~35 GB used | Start routing new users to next server |
-| RAM usage > 85% | ~43 GB used | Mark current server as "full" |
-| QPS sustained > 30 | Unlikely before 100K users | Add read replica |
-| Embedding queue depth > 100 | Very unlikely | Second GPU server |
-
-### Cost at Scale
-
-| Users | Servers | Monthly Cost | Cost/user/month |
-|---|---|---|---|
-| 1-5K | Existing infra | **$0** | $0 |
-| 5-30K | 1x GEX44 | **$200** | $0.007-0.04 |
-| 30-100K | GEX44 + AX162 | **$416** | $0.004-0.014 |
-| 100-300K | GEX44 + 2x AX162 | **$650-975** | $0.002-0.01 |
-| 300K-1M | GEX44 + Qdrant cluster | **$2,200-4,300** | $0.002-0.014 |
-
-### Hetzner vs AWS Comparison
-
-| Users | Hetzner | AWS | Multiplier |
-|---|---|---|---|
-| 30K | ~$200/mo | ~$1,267/mo | AWS is **6.3x** more |
-| 100K | ~$416/mo | ~$2,800/mo | AWS is **6.7x** more |
-| 300K | ~$975/mo | ~$5,500/mo | AWS is **5.6x** more |
-
-Hetzner's dedicated GPU servers are dramatically cheaper than cloud GPU instances. This is a structural cost advantage.
-
----
-
-## Architecture Diagram
-
-### Day 1 (you + early users)
-
-```
-Plugin ──→ existing Candengo Vector server
-           (memory is just another namespace)
-```
-
-### Growth (500-30K users)
-
-```
-Plugin ──→ mem.candengo.com ──→ GEX44 (single server)
-           (DNS points directly,    Qdrant + BGE-M3 + API
-            no router needed)       all on one box
-```
-
-### Scale (30K+ users)
-
-```
-                                    ┌─→ vec-eu-1 (GEX44 - GPU + API)
-Plugin ──→ mem.candengo.com ──→ Router
-           (Traefik or FastAPI)     └─→ vec-eu-2 (AX162 - Qdrant only)
-           api_key → backend lookup
-```
-
-### Big (100K+ users)
-
-```
-                                    ┌─→ vec-eu-1 (GPU + API)
-Plugin ──→ mem.candengo.com ──→ Router ──→ vec-eu-2 (Qdrant shard A)
-           (FastAPI proxy +         └─→ vec-eu-3 (Qdrant shard B)
-            Redis cache)
-                                    New users → lowest capacity shard
-                                    Existing users → assigned shard
-```
-
-Each step is additive. No rearchitecting. No downtime. No user-facing changes.

package/MARKET.md

@@ -1,230 +0,0 @@
-# Market Research — Engrm
-
-## Competitive Pricing Landscape
-
-### Direct Competitors (AI Agent Memory)
-
-| Product | Free Tier | Entry Paid | Mid Tier | Enterprise | Model |
-|---|---|---|---|---|---|
-| **Mem0** | 10K memories, 1K calls/mo | $19/mo (50K memories) | $249/mo (unlimited + graph) | Custom | Monthly sub + limits |
-| **Zep** | 1K credits/mo | $25/mo (20K credits) | $475/mo (300K credits) | Custom + BYOC | Credits (per-episode) |
-| **Letta (MemGPT)** | Free (beta) | TBD | TBD | TBD | Not yet launched |
-| **MemMachine** | Open source | Enterprise TBD | TBD | TBD | Self-hosted |
-| **MemoClaw** | 1K free calls | Pay-per-call ($0.001) | — | — | Crypto micro-payments |
-| **LangMem** | Open source | $0 (self-host) | $39/seat (LangSmith) | Custom | Platform bundled |
-
-### Vector DB Infrastructure (Potential Backends)
-
-| Product | Free Tier | Entry Paid | Enterprise | Funding |
-|---|---|---|---|---|
-| **Pinecone** | 2GB storage | $50/mo min | $500/mo min | $238M raised |
-| **Weaviate** | 14-day trial | ~$45/mo | ~$10K/yr | $67.7M raised |
-| **Qdrant** | 1GB cluster | Usage-based | Custom SLA | $28M raised |
-| **Chroma** | $5 credits | $250/mo (Team) | Custom | $18M raised |
-
-### Claude Code Memory Plugins (All Free/Open Source)
-
-| Plugin | Approach | Users |
-|---|---|---|
-| **claude-mem** | Auto-capture + ChromaDB + session summaries | Most popular |
-| **MemCP** | MCP server, 20x token reduction claims | Growing |
-| **Memory Anchor** | 5-layer cognitive memory model | Niche |
-| **memory-mcp** | Persistent memory + git snapshots | Small |
-| **mcp-memory-service** | REST API + knowledge graph + consolidation | Small |
-
-**Key insight**: Every Claude Code memory plugin is free. No one is charging yet. The value capture is happening at the platform layer (Mem0 $249/mo, Zep $475/mo), not the plugin layer.
-
----
-
-## Competitor Deep Dive
-
-### Mem0 — The Market Leader
-- **Funding**: $24M total ($3.9M seed + $20M Series A, Oct 2025)
-- **Investors**: Basis Set Ventures, Peak XV, YC, GitHub Fund
-- **Angels**: Dharmesh Shah (HubSpot), Thomas Dohmke (ex-GitHub CEO), Paul Copplestone (Supabase)
-- **Metrics**: 80K+ developers, 41K GitHub stars, 13M+ PyPI downloads
-- **API calls**: 35M (Q1 2025) → 186M (Q3 2025) — 5x growth in 6 months
-- **Partnerships**: AWS chose Mem0 as exclusive memory provider for Agent SDK
-- **Weakness**: SaaS-only (no self-hosted), $19→$249 pricing gap, no workpacks
-
-### Zep — Enterprise Focused
-- **Funding**: $2.3M total, YC W24
-- **Revenue**: Reported $1M in 2024 with 5-person team
-- **Differentiator**: Temporal knowledge graph (Graphiti) — models entities/relationships over time
-- **Offering**: SOC 2 Type II, HIPAA BAA, BYOC/BYOK/BYOM options
-- **Weakness**: Complex credit system, high mid-tier pricing ($475/mo)
-
-### Letta (formerly MemGPT) — The Academic Challenger
-- **Funding**: $10M seed from Felicis Ventures
-- **Angels**: Jeff Dean (Google), Clem Delangue (Hugging Face)
-- **Approach**: Memory as first-class agent state, not just a storage layer
-- **Recent**: Launched "Letta Code" — a memory-first coding agent (direct competitor territory)
-- **Weakness**: Early stage, no pricing, still in beta
-
----
-
-## Market Size
-
-### AI Coding Agent Users (Feb 2026)
-
-| Tool | Estimated Users | Paid Users |
-|---|---|---|
-| GitHub Copilot | ~20M cumulative | ~4.7M paid |
-| Cursor | ~2M | ~1M paid |
-| Claude Code | ~2-5M (est. from revenue) | Bundled with plans |
-| Cline | ~5M installs | Free (BYOK) |
-| OpenClaw | 100K+ GitHub stars | N/A (self-hosted) |
-| Windsurf | ~500K-1M (est.) | Unknown |
-| **Total (deduplicated)** | **~15-25M unique developers** | **~6-7M paying** |
-
-Note: 85% of developers regularly used AI tools for coding by end of 2025. Gartner predicts 75% of enterprise software engineers will use AI code assistants by 2028.
-
-### Total Addressable Market
-
-| Scope | Value (2025) | Projected (2030) | CAGR |
-|---|---|---|---|
-| AI coding assistants (narrow) | $3.9B | — | — |
-| AI code tools (mid) | $7.37B | $23.97B | 26.6% |
-| AI developer tools (broad) | $29.47B | — | — |
-
-### AI Memory Infrastructure Funding (2024-2025)
-
-| Company | Raised | Valuation |
-|---|---|---|
-| Mem0 | $24M | Undisclosed |
-| Letta | $10M | Undisclosed |
-| Memories.ai | $8M | Undisclosed |
-| Zep | $2.3M | Undisclosed |
-| **Total** | **~$44M+** | — |
-
-This validates that investors see AI memory as a distinct, fundable category.
-
----
-
-## Pricing Strategy Recommendation
-
-### Developer Tool Pricing Context
-
-- Typical developer spend on productivity tools: **$15-30/month**
-- Sweet spot for individual tools: **$10-20/month**
-- GitHub Copilot: $10/mo, Cursor: $20/mo, Windsurf: $15/mo
-
-### Free-to-Paid Conversion Benchmarks
-
-| Model | Conversion Rate |
-|---|---|
-| Freemium (self-serve) | 3-5% typical |
-| Freemium (sales-assisted) | 5-7% average |
-| Free trial (opt-in) | 18.2% median |
-| Dev tools trial-to-paid | 15-28% |
-| Open-source SaaS (mass market) | 0.3-1% |
-
-### Proposed Engrm Pricing
-
-| 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 + support SLA, SSO, audit, compliance | Large orgs |
-
-**Rationale**:
-- **Free tier includes cloud sync** — this is the key differentiator vs every other free plugin. 10K observations (~2-3 months of active use) is enough to get hooked, 2 devices covers the core laptop+desktop use case
-- **$9/mo Solo** undercuts Mem0's $19 entry and sits below Cursor's $20/mo — feels like a reasonable add-on, not a major commitment
-- **$19/mo Pro** matches Mem0's entry but gives unlimited (Mem0 caps at 50K memories for $19)
-- **$12/seat Team** is below Windsurf's $30/seat team pricing — easy budget approval
-- **Self-hosted is always free** — run your own Candengo Vector, no limits. Paid tiers are for the convenience of hosted infrastructure
-
-### Licensing Strategy
-
-**FSL-1.1-ALv2 (Functional Source License)** for the core client. Part of the [Fair Source](https://fair.io) movement (Sentry, Codecov, GitButler, Keygen). Source-available, free to use, but prevents competitors from offering a competing hosted service. Each version converts to Apache 2.0 after 2 years. Sentinel (real-time AI audit) is proprietary, in a separate private repo. This split model (open core + proprietary premium) follows the GitLab CE/EE pattern.
-
----
-
-## Influencer & Distribution Analysis
-
-### Developer YouTube Landscape
-
-| Creator | Subscribers | Avg Views | Reach Profile |
-|---|---|---|---|
-| **NetworkChuck** | ~5.1M | High | Broad tech, IT, networking |
-| **Fireship** | ~4.1M | 500K-2M | Developer-focused, fast-paced |
-| **ThePrimeagen** | ~527K | Varies | Performance, dev culture |
-| **Theo (t3.gg)** | ~472K | ~100K avg | Full-stack TypeScript |
-| **Greg Isenberg** | ~451K | Varies | AI business, startups |
-| **Alex Finn** | ~11K | Low thousands | AI tools for creators |
-
-### Conversion Estimates
-
-YouTube mention → signups funnel:
-```
-Video views → Landing page visits (1-5% CTR) → Signups (5-10% of visitors)
-Net: ~0.05-0.5% of video viewers sign up
-```
-
-| Scenario | Views | Est. Signups | At 4% conversion to paid | MRR impact |
-|---|---|---|---|---|
-| Alex Finn mention | ~5K | 25-50 | 1-2 paid | ~$19 |
-| Theo / ThePrimeagen | ~100K | 500-1,000 | 20-40 paid | ~$380-760 |
-| Fireship "100 seconds of..." | ~1M | 5,000-10,000 | 200-400 paid | ~$3,800-7,600 |
-| NetworkChuck tutorial | ~2M | 10,000-20,000 | 400-800 paid | ~$7,600-15,200 |
-
-### Realistic Launch Projections
-
-**Conservative (organic + 1-2 mid-tier YouTubers)**:
-
-| Timeframe | Free Users | Paid Users | MRR | ARR |
-|---|---|---|---|---|
-| Month 1 | 500 | 15 | $200 | $2.4K |
-| Month 3 | 3,000 | 120 | $1,600 | $19.2K |
-| Month 6 | 10,000 | 400 | $5,200 | $62.4K |
-| Month 12 | 30,000 | 1,200 | $15,600 | $187.2K |
-
-**Optimistic (Fireship or similar tier-1 coverage + strong product)**:
-
-| Timeframe | Free Users | Paid Users | MRR | ARR |
-|---|---|---|---|---|
-| Month 1 | 5,000 | 150 | $2,000 | $24K |
-| Month 3 | 20,000 | 800 | $10,400 | $124.8K |
-| Month 6 | 50,000 | 2,000 | $26,000 | $312K |
-| Month 12 | 100,000 | 5,000 | $65,000 | $780K |
-
-**Viral scenario (multiple tier-1 creators + HackerNews front page)**:
-
-| Timeframe | Free Users | Paid Users | MRR | ARR |
-|---|---|---|---|---|
-| Month 3 | 50,000 | 2,000 | $26,000 | $312K |
-| Month 6 | 150,000 | 6,000 | $78,000 | $936K |
-| Month 12 | 300,000 | 15,000 | $195,000 | $2.34M |
-
-### Key Growth Levers
-
-1. **Open-source GitHub repo** — stars drive organic discovery (see: OpenClaw 0→100K stars)
-2. **Claude Code marketplace** — built-in distribution to Claude Code's ~2-5M user base
-3. **OpenClaw skill directory** — access to 100K+ engaged community
-4. **HackerNews / Reddit launches** — dev tool launches regularly hit front page
-5. **Content marketing** — comparison posts (vs Mem0), tutorials, integration guides
-6. **Word of mouth from teams** — each team member who uses it tells others
-7. **Workpack partnerships** — co-branded content with framework communities
-
-### Comparable Growth Trajectories
-
-- **Mem0**: 0 → 41K GitHub stars, 80K developers, $24M funding in ~18 months
-- **Cursor**: $1M → $1B ARR in 24 months (fastest B2B SaaS ever)
-- **OpenClaw**: 0 → 100K GitHub stars in weeks after going viral
-- **Supabase**: 1M → 4.5M developers in under a year (content-led growth)
-
----
-
-## Strategic Pricing Insights
-
-1. **Mem0's $19→$249 gap is an opportunity**: Many developers need more than the free tier but can't justify $249/mo. Our $9 Solo and $19 Pro tiers sit in that gap.
-
-2. **Self-hosted free tier is a trust builder**: Developers are sceptical of sending code context to clouds. "Here, run it yourself for free" builds trust that converts to paid cloud convenience.
-
-3. **Team pricing is where the real revenue is**: $12/seat × 10 developers = $120/mo per team. Enterprise teams are less price-sensitive and have procurement budgets.
-
-4. **Workpacks are high-margin recurring revenue**: Content costs to produce once, generates revenue indefinitely. Premium workpacks at $5-10/mo add-on could be significant.
-
-5. **The plugin layer is free; the premium layer is paid**: Core client under FSL (free to use, converts to Apache 2.0 after 2yr). Sentinel (real-time AI audit) and Candengo Vector hosting are the revenue drivers. This matches the GitLab CE/EE pattern.