@traqr/memory 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# TraqrDB — Memory-as-a-Service for AI Agents
+
+A schema + intelligence layer on top of Postgres + pgvector. Store memories, search by meaning, track entity relationships, manage memory lifecycle — all via 10 MCP tools.
+
+## Quick Start (10 minutes)
+
+### 1. Set Up Your Database
+
+**Option A: Supabase (easiest, free tier)**
+1. Create a project at [supabase.com](https://supabase.com)
+2. Go to SQL Editor, paste contents of `setup.sql`, run
+3. Copy your project URL + service role key from Settings > API
+
+**Option B: AWS RDS / Aurora**
+1. Create RDS Postgres 15+ instance
+2. Enable pgvector: `CREATE EXTENSION vector;`
+3. Run setup.sql via psql: `psql $DATABASE_URL -f setup.sql`
+
+**Option C: Docker (local dev)**
+```bash
+docker run -d --name traqrdb \
+  -e POSTGRES_PASSWORD=postgres \
+  -p 5432:5432 \
+  pgvector/pgvector:pg16
+psql postgresql://postgres:postgres@localhost:5432/postgres -f setup.sql
+```
+
+### 2. Configure Environment
+
+```bash
+# Required: Postgres connection
+export DATABASE_URL="postgresql://user:pass@host:5432/dbname"
+# OR for Supabase:
+export SUPABASE_URL="https://xxx.supabase.co"
+export SUPABASE_SERVICE_ROLE_KEY="eyJ..."
+
+# Embedding provider (choose one)
+export OPENAI_API_KEY="sk-..."        # OpenAI ($0.02/1M tokens)
+export GOOGLE_API_KEY="AIza..."       # Gemini Embedding 2 (free tier)
+# OR neither — entities use name matching, no semantic search
+
+# Optional
+export COHERE_API_KEY="..."           # Cohere Rerank v3.5
+```
+
+### 3. Connect to Your AI Agent
+
+Add to your MCP client config (Claude Code, Cursor, etc.):
+```json
+{
+  "traqr-memory": {
+    "command": "npx",
+    "args": ["traqr-memory-mcp"],
+    "env": {
+      "DATABASE_URL": "postgresql://...",
+      "OPENAI_API_KEY": "sk-..."
+    }
+  }
+}
+```
+
+### 4. Verify
+
+Use `memory_audit` to check health, then `memory_store` to create your first memory.
+
+---
+
+## 10 MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_store` | Remember something. Only content required — everything else auto-derived. |
+| `memory_search` | Search memories by meaning. Returns summaries. |
+| `memory_read` | Expand a memory by ID. Full content + version history. |
+| `memory_enhance` | Deepen understanding. Creates connected memories via triage pipeline. |
+| `memory_browse` | Navigate by facet. Domain > category > summaries. Zero embedding cost. |
+| `memory_context` | Load task-relevant context — principles, preferences, gotchas. |
+| `memory_pulse` | Batch: capture multiple learnings + search + update in one call. |
+| `memory_audit` | System health, stats, quality metrics. |
+| `memory_archive` | Archive stale content that was once correct. |
+| `memory_forget` | Forget incorrect or harmful content permanently. |
+
+## What's Inside
+
+**Schema** (created by `setup.sql`):
+- `traqr_memories` — content, embeddings, lifecycle, dual tsvectors
+- `memory_relationships` — graph edges between memories
+- `memory_entities` — extracted entities with embeddings
+- `memory_entity_links` — memory-to-entity junction table
+- 12+ indexes including partial HNSW, BM25 GIN, lifecycle
+- 10+ RPC functions for search, BM25, temporal, graph, confidence decay
+
+**Intelligence** (in the TypeScript package):
+- Multi-strategy retrieval: semantic + BM25 > RRF fusion > optional Cohere rerank
+- 3-zone cosine triage: NOOP (>=0.90), ADD (<0.60), borderline (GPT-4o-mini decision)
+- Type-aware lifecycle: facts invalidate, preferences supersede, patterns coexist
+- Entity extraction: multi-signal canonicalization (name > ILIKE > embedding)
+- Quality gate: 3-layer ingestion filter prevents noise
+
+## Graceful Degradation
+
+| Missing | Behavior |
+|---------|----------|
+| No embedding API key | Entities use name matching. BM25 keyword search works. No vector search. |
+| No COHERE_API_KEY | Search uses RRF scores instead of Cohere rerank. |
+
+## TypeScript Library API
+
+```typescript
+import { storeMemory, searchMemories, triageAndStore } from '@traqr/memory'
+
+// Store a memory
+await storeMemory({ content: 'Always use bun', sourceType: 'manual' })
+
+// Search by meaning
+const results = await searchMemories('package manager', { limit: 5 })
+
+// Store with triage (dedup + edges + LLM borderline)
+const result = await triageAndStore({ content: '...', sourceType: 'session' })
+// result.zone: 'noop' | 'add' | 'borderline'
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` or `SUPABASE_URL` | Yes | Postgres connection |
+| `SUPABASE_SERVICE_ROLE_KEY` | Supabase only | Service role key |
+| `OPENAI_API_KEY` | Recommended | OpenAI embeddings |
+| `GOOGLE_API_KEY` | Alternative | Gemini Embedding 2 (free) |
+| `COHERE_API_KEY` | No | Cohere Rerank (quality boost) |
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @traqr/memory — Public API
+ *
+ * Vector DB client, memory operations, and standalone HTTP server
+ * for the Traqr memory system.
+ */
+export { createMemoryServer } from './server.js';
+export { getVectorDB, resetVectorDB } from './vectordb/index.js';
+export type { VectorDBProvider, Memory, MemoryInput, MemorySearchResult, MemoryUpdate, MemoryExport, MemoryDomain, SearchOptions, MemoryCategory, MemorySourceType, MemoryDurability, MemoryType, BM25SearchResult, TemporalSearchResult, GraphSearchResult, ProviderConfig, } from './vectordb/types.js';
+export { BOOTSTRAP_CONFIDENCE, DECAY_CONFIG } from './vectordb/types.js';
+export { deriveAll, deriveDomain, deriveCategory, deriveTopic, deriveSummary, deriveTags, deriveMemoryType, deriveForgetAfter, extractEntityCandidates, } from './lib/auto-derive.js';
+export type { DeriveResult, EntityCandidate } from './lib/auto-derive.js';
+export { borderlineDecision } from './lib/borderline.js';
+export type { BorderlineDecision, BorderlineAction, MaskedMemory } from './lib/borderline.js';
+export { cohereRerank } from './lib/rerank.js';
+export type { RerankResult, RerankDocument } from './lib/rerank.js';
+export { storeMemory, searchMemories, getMemory, updateMemory, deleteMemory, validateMemory, archiveMemory, unarchiveMemory, exportAllMemories, importMemories, storeWithDedup, triageAndStore, createRelationship, invalidateMemory, supersedeMemory, remember, recall, isMemoryHealthy, getMemoryStats, getDetailedStats, getSystemHealth, verifyRoundTrip, formatMemory, formatSearchResults, } from './lib/memory.js';
+export { getVersionChain, getMemoryHistory, getMemoryRelationships, } from './lib/lifecycle.js';
+export type { MemoryHistoryResult, MemoryRelationship } from './lib/lifecycle.js';
+export { processEntitiesForMemory } from './lib/entity-pipeline.js';
+export type { EntityExtractionResult } from './lib/entity-pipeline.js';
+export type { StoreWithDedupResult, TriageResult, TriageZone, TriageAction, TriageOptions, RoundTripResult, DetailedStats, SystemHealth, } from './lib/memory.js';
+export { searchMemoriesV2, reciprocalRankFusion, detectStrategies, parseTemporalRange, findEntitiesInQuery, } from './lib/retrieval.js';
+export type { SearchV2Options, SearchStrategy, FusedItem, StrategyResult, DetectedStrategies, } from './lib/retrieval.js';
+export { generateEmbedding, generateEmbeddingsBatch, cosineSimilarity, formatEmbeddingForPgVector, parseEmbeddingFromPgVector, needsReembedding, checkEmbeddingHealth, EMBEDDING_CONFIG, } from './lib/embeddings.js';
+export type { EmbeddingResult, EmbeddingHealthStatus } from './lib/embeddings.js';
+export { CATEGORY_EMOJI, CATEGORY_EMOJI_SLACK, CATEGORY_EMOJI_TEXT, SOURCE_TYPE_EMOJI, getCategoryEmoji, } from './lib/formatting.js';
+export { getMemoryClient, resetMemoryClient, getUserId, getProjectId, configureMemory, getTableName } from './lib/client.js';
+export type { MemoryClientConfig } from './lib/client.js';
+export { verifyAuth, requireAuth, getInternalSecret } from './lib/auth.js';
+export { assembleSessionContext } from './lib/context.js';
+export type { SessionContextParams, SessionContext, MemoryWithShortCode } from './lib/context.js';
+export { extractLearningsFromPR, batchExtractLearnings, submitManualLearning, extractFromConversation, extractFromSessionDiff, extractLearningsFromPlan, extractFromCodebaseAnalysis, extractVoiceTraits, detectContradictions, formatExtractionResult, getSourceProject, } from './lib/learning-extractor.js';
+export type { PRContext, ExtractedLearning, ExtractionResult, SuggestedLayer, SessionDiffContext, SessionExtractionResult, PlanContext, CodebaseAnalysisContext, CodebaseAnalysisResult, ContradictionResult, VoiceAnalysisType, VoiceAnalysisContext, VoiceAnalysisResult, } from './lib/learning-extractor.js';

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAGhD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAChE,YAAY,EACV,gBAAgB,EAChB,MAAM,EACN,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,GACf,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGxE,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,QAAQ,EACR,MAAM,EACN,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGzG,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,0BAA0B,EAC1B,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAA;AAGjF,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAA;AAG5B,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC5H,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAGzD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAG1E,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AACzD,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAGjG,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EACvB,WAAW,EACX,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,6BAA6B,CAAA"}

package/dist/index.js

@@ -0,0 +1,38 @@
+/**
+ * @traqr/memory — Public API
+ *
+ * Vector DB client, memory operations, and standalone HTTP server
+ * for the Traqr memory system.
+ */
+// Server
+export { createMemoryServer } from './server.js';
+// VectorDB layer
+export { getVectorDB, resetVectorDB } from './vectordb/index.js';
+export { BOOTSTRAP_CONFIDENCE, DECAY_CONFIG } from './vectordb/types.js';
+// Auto-derive v2
+export { deriveAll, deriveDomain, deriveCategory, deriveTopic, deriveSummary, deriveTags, deriveMemoryType, deriveForgetAfter, extractEntityCandidates, } from './lib/auto-derive.js';
+// LLM borderline decision
+export { borderlineDecision } from './lib/borderline.js';
+// Cohere rerank
+export { cohereRerank } from './lib/rerank.js';
+// High-level memory operations
+export { storeMemory, searchMemories, getMemory, updateMemory, deleteMemory, validateMemory, archiveMemory, unarchiveMemory, exportAllMemories, importMemories, storeWithDedup, triageAndStore, createRelationship, invalidateMemory, supersedeMemory, remember, recall, isMemoryHealthy, getMemoryStats, getDetailedStats, getSystemHealth, verifyRoundTrip, formatMemory, formatSearchResults, } from './lib/memory.js';
+// Lifecycle utilities
+export { getVersionChain, getMemoryHistory, getMemoryRelationships, } from './lib/lifecycle.js';
+// Entity extraction pipeline
+export { processEntitiesForMemory } from './lib/entity-pipeline.js';
+// Multi-strategy retrieval (v2)
+export { searchMemoriesV2, reciprocalRankFusion, detectStrategies, parseTemporalRange, findEntitiesInQuery, } from './lib/retrieval.js';
+// Embeddings
+export { generateEmbedding, generateEmbeddingsBatch, cosineSimilarity, formatEmbeddingForPgVector, parseEmbeddingFromPgVector, needsReembedding, checkEmbeddingHealth, EMBEDDING_CONFIG, } from './lib/embeddings.js';
+// Formatting
+export { CATEGORY_EMOJI, CATEGORY_EMOJI_SLACK, CATEGORY_EMOJI_TEXT, SOURCE_TYPE_EMOJI, getCategoryEmoji, } from './lib/formatting.js';
+// Client configuration
+export { getMemoryClient, resetMemoryClient, getUserId, getProjectId, configureMemory, getTableName } from './lib/client.js';
+// Auth middleware
+export { verifyAuth, requireAuth, getInternalSecret } from './lib/auth.js';
+// Context assembly
+export { assembleSessionContext } from './lib/context.js';
+// Learning extractor
+export { extractLearningsFromPR, batchExtractLearnings, submitManualLearning, extractFromConversation, extractFromSessionDiff, extractLearningsFromPlan, extractFromCodebaseAnalysis, extractVoiceTraits, detectContradictions, formatExtractionResult, getSourceProject, } from './lib/learning-extractor.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,SAAS;AACT,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhD,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAmBhE,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAExE,iBAAiB;AACjB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,cAAc,EACd,WAAW,EACX,aAAa,EACb,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,sBAAsB,CAAA;AAG7B,0BAA0B;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAGxD,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAG9C,+BAA+B;AAC/B,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,MAAM,EACN,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,mBAAmB,GACpB,MAAM,iBAAiB,CAAA;AAExB,sBAAsB;AACtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,oBAAoB,CAAA;AAG3B,6BAA6B;AAC7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AAcnE,gCAAgC;AAChC,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,oBAAoB,CAAA;AAS3B,aAAa;AACb,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,0BAA0B,EAC1B,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,qBAAqB,CAAA;AAG5B,aAAa;AACb,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,qBAAqB,CAAA;AAE5B,uBAAuB;AACvB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAG5H,kBAAkB;AAClB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAE1E,mBAAmB;AACnB,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAGzD,qBAAqB;AACrB,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,6BAA6B,CAAA"}

package/dist/lib/auth.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Portable Auth Middleware for @traqr/memory
+ *
+ * Bearer token auth using INTERNAL_API_KEY or CRON_SECRET env vars.
+ * If neither is set, auth is skipped (dev mode).
+ */
+import type { Context, Next } from 'hono';
+export declare function getInternalSecret(): string | undefined;
+/**
+ * Verify Bearer token auth on a Hono context.
+ * Returns true if auth passes or no secret is configured.
+ */
+export declare function verifyAuth(c: Context): boolean;
+/**
+ * Hono middleware that enforces internal auth.
+ * Returns 401 if auth fails.
+ */
+export declare function requireAuth(c: Context, next: Next): Promise<Response | void>;

package/dist/lib/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/lib/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAEzC,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAK9C;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAKlF"}

package/dist/lib/auth.js

@@ -0,0 +1,31 @@
+/**
+ * Portable Auth Middleware for @traqr/memory
+ *
+ * Bearer token auth using INTERNAL_API_KEY or CRON_SECRET env vars.
+ * If neither is set, auth is skipped (dev mode).
+ */
+export function getInternalSecret() {
+    return process.env.INTERNAL_API_KEY || process.env.CRON_SECRET;
+}
+/**
+ * Verify Bearer token auth on a Hono context.
+ * Returns true if auth passes or no secret is configured.
+ */
+export function verifyAuth(c) {
+    const secret = getInternalSecret();
+    if (!secret)
+        return true; // No secret = dev mode, skip auth
+    const auth = c.req.header('authorization');
+    return auth === `Bearer ${secret}`;
+}
+/**
+ * Hono middleware that enforces internal auth.
+ * Returns 401 if auth fails.
+ */
+export async function requireAuth(c, next) {
+    if (!verifyAuth(c)) {
+        return c.json({ error: 'Unauthorized' }, 401);
+    }
+    await next();
+}
+//# sourceMappingURL=auth.js.map

package/dist/lib/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/lib/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAA;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,CAAU;IACnC,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAA;IAClC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA,CAAC,kCAAkC;IAC3D,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA;IAC1C,OAAO,IAAI,KAAK,UAAU,MAAM,EAAE,CAAA;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,CAAU,EAAE,IAAU;IACtD,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QACnB,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,GAAG,CAAC,CAAA;IAC/C,CAAC;IACD,MAAM,IAAI,EAAE,CAAA;AACd,CAAC"}

package/dist/lib/auto-derive.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Auto-Derive v2 — Consolidated field derivation module
+ *
+ * Infers domain, category, topic, summary, tags, memoryType, and more
+ * from memory content. Single source of truth — imported by MCP server,
+ * pulse route, store route, and any future ingestion path.
+ *
+ * ADR: [[MCP Redesign — Auto-Derive Module]]
+ */
+import type { MemoryType } from '../vectordb/types.js';
+export interface EntityCandidate {
+    name: string;
+    type: string;
+}
+export interface DeriveResult {
+    domain: string;
+    category: string;
+    topic?: string;
+    summary: string;
+    tags: string[];
+    memoryType: MemoryType;
+    forgetAfter?: Date;
+    sourceTool?: string;
+    entityCandidates: EntityCandidate[];
+}
+export declare function deriveDomain(content: string): string;
+export declare function deriveCategory(content: string): string;
+export declare function deriveTopic(content: string): string | undefined;
+export declare function deriveSummary(content: string): string;
+export declare function deriveTags(content: string, category: string): string[];
+export declare function deriveMemoryType(content: string, category: string): MemoryType;
+export declare function deriveForgetAfter(content: string): Date | undefined;
+export declare function deriveSourceTool(explicit?: string): string | undefined;
+export declare function extractEntityCandidates(content: string): EntityCandidate[];
+export declare function deriveAll(content: string, overrides?: Partial<DeriveResult>): DeriveResult;

package/dist/lib/auto-derive.js

@@ -0,0 +1,261 @@
+/**
+ * Auto-Derive v2 — Consolidated field derivation module
+ *
+ * Infers domain, category, topic, summary, tags, memoryType, and more
+ * from memory content. Single source of truth — imported by MCP server,
+ * pulse route, store route, and any future ingestion path.
+ *
+ * ADR: [[MCP Redesign — Auto-Derive Module]]
+ */
+// ============================================================
+// 1. deriveDomain — detect domain from content
+// ============================================================
+export function deriveDomain(content) {
+    const c = content.toLowerCase();
+    if (/\bsean\b/.test(c) || /\b(prefer|personality|background|vibe.cod|credit.card|llc|traqr enterprises)/i.test(c))
+        return 'sean';
+    if (/\b(traqr|worktree|guardian|slot.system|daemon|memory.*(system|db)|\.traqr\/|traqr-init)/i.test(c))
+        return 'traqr';
+    if (/\b(nooktraqr|animal.crossing|villager|island.profile|turnip)/i.test(c))
+        return 'nooktraqr';
+    if (/\b(pokotraqr|pokopia|pokop)/i.test(c))
+        return 'pokotraqr';
+    if (/\b(poketraqr|pokemon)/i.test(c))
+        return 'poketraqr';
+    if (/\b(milestraqr|miles.voyager)/i.test(c))
+        return 'milestraqr';
+    if (/\b(jiggy|capital|portfolio|earnings|koyfin)/i.test(c))
+        return 'jiggy';
+    if (/\b(supabase|vercel|cloudflare|openai|linear|slack|github|firebase|clerk|resend|posthog)/i.test(c))
+        return 'tooling';
+    return 'universal';
+}
+// ============================================================
+// 2. deriveCategory — detect category from content
+// ============================================================
+export function deriveCategory(content) {
+    const c = content.toLowerCase();
+    if (/\b(gotcha|critical|never\s+trust|always\s+check|warning|silently.fail|broke\b)/i.test(c))
+        return 'gotcha';
+    if (/\b(fix|bug|root.cause|resolved|patch|was.broken|caused.by)/i.test(c))
+        return 'fix';
+    if (/\b(prefer|values?|wants?|hates?|loves?|style|personality|blunt|direct)/i.test(c))
+        return 'preference';
+    if (/\b(pattern|approach|technique|strategy|method|architecture|flywheel)/i.test(c))
+        return 'pattern';
+    if (/\b(convention|rule|naming|structure|format|must.be|required)/i.test(c))
+        return 'convention';
+    if (/\b(question|unclear|investigate|explore|wonder|unsolved)/i.test(c))
+        return 'question';
+    return 'insight';
+}
+// ============================================================
+// 3. deriveTopic — 18-topic scoring algorithm
+// ============================================================
+const TOPIC_KEYWORDS = {
+    supabase: ['supabase', 'rpc', 'pgvector', 'rls', 'migration'],
+    git: ['git', 'rebase', 'merge', 'commit', 'branch', 'push', 'stash'],
+    vercel: ['vercel', 'serverless', 'edge function', 'hobby tier'],
+    cloudflare: ['cloudflare', 'workers', 'cron trigger', 'd1'],
+    linear: ['linear', 'ticket', 'issue', 'agent-ready'],
+    slack: ['slack', 'channel', 'webhook', 'thread'],
+    auth: ['auth', 'login', 'session', 'token', 'clerk', 'firebase auth'],
+    deployment: ['deploy', 'production', 'build', 'ci/cd', 'ship'],
+    design: ['design', 'ui', 'ux', 'dark mode', 'component', 'layout'],
+    architecture: ['architecture', 'monorepo', 'package', 'platform', 'system design'],
+    business: ['llc', 'business', 'revenue', 'pricing', 'saas'],
+    'personal-finance': ['credit card', 'points', 'miles', 'amex', 'chase', 'capital one', 'sign-up bonus'],
+    'product-strategy': ['product', 'roadmap', 'mvp', 'launch', 'users', 'growth'],
+    'memory-system': ['memory', 'vector', 'embedding', 'pgvector', 'learning'],
+    testing: ['test', 'e2e', 'verify', 'assertion'],
+    seo: ['seo', 'sitemap', 'indexing', 'google search', 'gsc'],
+    personality: ['personality', 'communication', 'decision-making', 'values'],
+    workflow: ['workflow', 'process', 'shipping', 'velocity', 'bottleneck'],
+};
+export function deriveTopic(content) {
+    const c = content.toLowerCase();
+    let bestTopic;
+    let bestScore = 0;
+    for (const [topic, keywords] of Object.entries(TOPIC_KEYWORDS)) {
+        const score = keywords.filter(kw => c.includes(kw)).length;
+        if (score > bestScore) {
+            bestScore = score;
+            bestTopic = topic;
+        }
+    }
+    return bestTopic;
+}
+// ============================================================
+// 4. deriveSummary — first meaningful sentence, max 120 chars
+// ============================================================
+export function deriveSummary(content) {
+    const lines = content.split(/\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('```'))
+            continue;
+        const firstSentence = trimmed.split(/(?<=[.!?])\s/)[0];
+        if (firstSentence && firstSentence.length <= 120)
+            return firstSentence;
+        return trimmed.slice(0, 117) + '...';
+    }
+    return content.slice(0, 117) + '...';
+}
+// ============================================================
+// 5. deriveTags — provenance, lifecycle, importance
+// ============================================================
+export function deriveTags(content, category) {
+    const tags = [];
+    const c = content.toLowerCase();
+    // Provenance
+    if (/\b(broke|incident|failure|crashed|lost.data|silently|wipe)/i.test(c))
+        tags.push('from-incident');
+    else if (/\b(decided|chose|opted|picked|ruled.out|went.with)/i.test(c))
+        tags.push('from-decision');
+    else
+        tags.push('from-observation');
+    // Lifecycle
+    if (/\b(always|never|every.time|mandatory|non-negotiable|universal)/i.test(c))
+        tags.push('evergreen');
+    else
+        tags.push('active');
+    // Importance
+    if (category === 'gotcha' || /\bcritical\b/i.test(c))
+        tags.push('critical');
+    else if (category === 'preference' || category === 'convention')
+        tags.push('important');
+    else
+        tags.push('nice-to-know');
+    return tags;
+}
+// ============================================================
+// 6. deriveMemoryType — classify fact/preference/pattern (v2)
+// ============================================================
+export function deriveMemoryType(content, category) {
+    // Preference: category already detected, or strong preference signals
+    if (category === 'preference')
+        return 'preference';
+    if (/\b(prefers?|prioritizes?|values?|avoids?|hates?|loves?|style|personality)\b/i.test(content))
+        return 'preference';
+    // Fact: assertions with numbers, dates, proper nouns + copula
+    if (/\b(is|are|was|has|have|costs?|weighs?|measures?)\s+\d/i.test(content))
+        return 'fact';
+    if (/\b(born|founded|created|established|started)\s+(in|on|at)\s+\d/i.test(content))
+        return 'fact';
+    if (/\b(located|based|headquartered)\s+(in|at)\b/i.test(content))
+        return 'fact';
+    if (/\bblood.type\b/i.test(content))
+        return 'fact';
+    // Default: pattern
+    return 'pattern';
+}
+// ============================================================
+// 7. deriveForgetAfter — detect temporal content (v2)
+// ============================================================
+export function deriveForgetAfter(content) {
+    const c = content.toLowerCase();
+    // "this week/month/sprint" -> 7/30/14 days from now + buffer
+    if (/\bthis\s+week\b/i.test(c)) {
+        const d = new Date();
+        d.setDate(d.getDate() + 14); // end of week + 7 day buffer
+        return d;
+    }
+    if (/\bthis\s+sprint\b/i.test(c)) {
+        const d = new Date();
+        d.setDate(d.getDate() + 21); // ~2 week sprint + 7 day buffer
+        return d;
+    }
+    if (/\bthis\s+month\b/i.test(c)) {
+        const d = new Date();
+        d.setDate(d.getDate() + 37); // end of month + 7 day buffer
+        return d;
+    }
+    // "by <day>" or "deadline <day>" -> attempt to parse
+    const deadlineMatch = c.match(/\b(?:by|deadline|due|before)\s+(\w+\s+\d{1,2}(?:,?\s+\d{4})?)/i);
+    if (deadlineMatch) {
+        const parsed = new Date(deadlineMatch[1]);
+        if (!isNaN(parsed.getTime())) {
+            parsed.setDate(parsed.getDate() + 7); // 7 day buffer
+            return parsed;
+        }
+    }
+    return undefined;
+}
+// ============================================================
+// 8. deriveSourceTool — explicit, not auto-detected (v2)
+// ============================================================
+// Callers pass their own identity: 'mcp-store', 'mcp-pulse', 'http-store', etc.
+// This function exists for consistency in the deriveAll interface.
+export function deriveSourceTool(explicit) {
+    return explicit || undefined;
+}
+// ============================================================
+// 9. extractEntityCandidates — regex NER (v2)
+// ============================================================
+export function extractEntityCandidates(content) {
+    const candidates = [];
+    const seen = new Set();
+    // Capitalized multi-word names (e.g., "Sean Fitzsimons", "Animal Crossing")
+    const nameMatches = content.match(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b/g);
+    if (nameMatches) {
+        for (const name of nameMatches) {
+            const key = name.toLowerCase();
+            if (!seen.has(key)) {
+                seen.add(key);
+                candidates.push({ name, type: 'person' }); // default to person, can be reclassified
+            }
+        }
+    }
+    // ALL_CAPS acronyms 2+ chars (e.g., AWS, API, SQL, BMI)
+    const acronymMatches = content.match(/\b[A-Z]{2,}\b/g);
+    if (acronymMatches) {
+        const skipAcronyms = new Set(['OR', 'AND', 'NOT', 'THE', 'FOR', 'BUT', 'NOR', 'YET', 'IF', 'AS', 'IN', 'ON', 'AT', 'TO', 'IS', 'IT', 'BY', 'OF', 'NO', 'DO', 'SO', 'UP', 'AM', 'PM', 'OK', 'VS']);
+        for (const acr of acronymMatches) {
+            if (!skipAcronyms.has(acr) && !seen.has(acr.toLowerCase())) {
+                seen.add(acr.toLowerCase());
+                candidates.push({ name: acr, type: 'technology' }); // default to technology
+            }
+        }
+    }
+    // Known technology patterns (PascalCase single words like React, Supabase, TypeScript)
+    const techMatches = content.match(/\b(?:React|Supabase|Vercel|Cloudflare|TypeScript|JavaScript|PostgreSQL?|Redis|Docker|Kubernetes|NextJS|Node|Python|Rust|GraphQL|Prisma|Drizzle)\b/g);
+    if (techMatches) {
+        for (const tech of techMatches) {
+            const key = tech.toLowerCase();
+            if (!seen.has(key)) {
+                seen.add(key);
+                candidates.push({ name: tech, type: 'technology' });
+            }
+        }
+    }
+    // Known company patterns
+    const companyMatches = content.match(/\b(?:Google|Apple|Amazon|Microsoft|Meta|Netflix|Anthropic|OpenAI|GitHub|Linear|Slack|Stripe|Twilio)\b/g);
+    if (companyMatches) {
+        for (const company of companyMatches) {
+            const key = company.toLowerCase();
+            if (!seen.has(key)) {
+                seen.add(key);
+                candidates.push({ name: company, type: 'company' });
+            }
+        }
+    }
+    return candidates;
+}
+// ============================================================
+// Orchestrator — derive all fields, respecting explicit overrides
+// ============================================================
+export function deriveAll(content, overrides = {}) {
+    const category = overrides.category || deriveCategory(content);
+    return {
+        domain: overrides.domain || deriveDomain(content),
+        category,
+        topic: overrides.topic || deriveTopic(content),
+        summary: overrides.summary || deriveSummary(content),
+        tags: overrides.tags?.length ? overrides.tags : deriveTags(content, category),
+        memoryType: overrides.memoryType || deriveMemoryType(content, category),
+        forgetAfter: overrides.forgetAfter || deriveForgetAfter(content),
+        sourceTool: overrides.sourceTool,
+        entityCandidates: extractEntityCandidates(content),
+    };
+}
+//# sourceMappingURL=auto-derive.js.map

package/dist/lib/auto-derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-derive.js","sourceRoot":"","sources":["../../src/lib/auto-derive.ts"],"names":[],"mappings":"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"}

package/dist/lib/borderline.d.ts

@@ -0,0 +1,26 @@
+/**
+ * LLM Borderline Decision Module
+ *
+ * When cosine triage hits Zone 3 (0.60-0.90 similarity),
+ * this module uses GPT-4o-mini to decide: ADD, UPDATE, or NOOP.
+ * UUID masking prevents the LLM from hallucinating memory IDs.
+ *
+ * Fallback: if LLM fails for ANY reason, caller uses I-M6 heuristic.
+ */
+export type BorderlineAction = 'add' | 'update' | 'noop';
+export interface BorderlineDecision {
+    action: BorderlineAction;
+    target?: string;
+    edgeType: 'updates' | 'extends' | 'related' | null;
+    reasoning: string;
+}
+export interface MaskedMemory {
+    label: string;
+    content: string;
+    memoryType?: string;
+}
+/**
+ * Ask GPT-4o-mini to classify a borderline memory.
+ * Returns null on any failure — caller should fall back to heuristic.
+ */
+export declare function borderlineDecision(newContent: string, existingMemories: MaskedMemory[], memoryType: string): Promise<BorderlineDecision | null>;