@traqr/memory 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +93 -102
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,134 +1,125 @@
1
- # TraqrDB — Memory-as-a-Service for AI Agents
1
+ # @traqr/memory
2
2
 
3
- 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.
3
+ TypeScript library for persistent AI agent memory. Multi-strategy retrieval (semantic + BM25 + RRF), 3-zone cosine triage, entity extraction, type-aware lifecycle. Postgres + pgvector.
4
4
 
5
- ## Quick Start (10 minutes)
5
+ Use this library if you're building your own memory-powered application. For an MCP server that works out of the box, see [traqr-memory-mcp](https://www.npmjs.com/package/traqr-memory-mcp).
6
6
 
7
- ### 1. Set Up Your Database
7
+ ## Install
8
8
 
9
- **Option A: Supabase (easiest, free tier)**
10
- 1. Create a project at [supabase.com](https://supabase.com)
11
- 2. Go to SQL Editor, paste contents of `setup.sql`, run
12
- 3. Copy your project URL + service role key from Settings > API
13
-
14
- **Option B: AWS RDS / Aurora**
15
- 1. Create RDS Postgres 15+ instance
16
- 2. Enable pgvector: `CREATE EXTENSION vector;`
17
- 3. Run setup.sql via psql: `psql $DATABASE_URL -f setup.sql`
18
-
19
- **Option C: Docker (local dev)**
20
9
  ```bash
21
- docker run -d --name traqrdb \
22
- -e POSTGRES_PASSWORD=postgres \
23
- -p 5432:5432 \
24
- pgvector/pgvector:pg16
25
- psql postgresql://postgres:postgres@localhost:5432/postgres -f setup.sql
10
+ npm install @traqr/memory
26
11
  ```
27
12
 
28
- ### 2. Configure Environment
13
+ ## Quick Usage
29
14
 
30
- ```bash
31
- # Required: Postgres connection
32
- export DATABASE_URL="postgresql://user:pass@host:5432/dbname"
33
- # OR for Supabase:
34
- export SUPABASE_URL="https://xxx.supabase.co"
35
- export SUPABASE_SERVICE_ROLE_KEY="eyJ..."
36
-
37
- # Embedding provider (choose one)
38
- export OPENAI_API_KEY="sk-..." # OpenAI ($0.02/1M tokens)
39
- export GOOGLE_API_KEY="AIza..." # Gemini Embedding 2 (free tier)
40
- # OR neither — entities use name matching, no semantic search
41
-
42
- # Optional
43
- export COHERE_API_KEY="..." # Cohere Rerank v3.5
44
- ```
15
+ ```typescript
16
+ import { configureMemory, storeMemory, searchMemoriesV2, triageAndStore } from '@traqr/memory'
17
+
18
+ // Configure once at startup
19
+ configureMemory({
20
+ supabaseUrl: process.env.SUPABASE_URL,
21
+ supabaseKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
22
+ })
23
+ // OR for raw Postgres:
24
+ configureMemory({
25
+ databaseUrl: process.env.DATABASE_URL,
26
+ })
45
27
 
46
- ### 3. Connect to Your AI Agent
47
-
48
- Add to your MCP client config (Claude Code, Cursor, etc.):
49
- ```json
50
- {
51
- "traqr-memory": {
52
- "command": "npx",
53
- "args": ["traqr-memory-mcp"],
54
- "env": {
55
- "DATABASE_URL": "postgresql://...",
56
- "OPENAI_API_KEY": "sk-..."
57
- }
58
- }
59
- }
28
+ // Store a memory
29
+ const memory = await storeMemory({
30
+ content: 'React Server Components require "use client" for interactive components',
31
+ sourceType: 'session',
32
+ })
33
+
34
+ // Search by meaning (multi-strategy: semantic + BM25 + RRF fusion)
35
+ const results = await searchMemoriesV2('React component patterns', { limit: 5 })
36
+
37
+ // Store with deduplication triage (cosine similarity zones + LLM borderline)
38
+ const result = await triageAndStore({
39
+ content: 'Always use useCallback for event handlers passed to memoized children',
40
+ sourceType: 'session',
41
+ })
42
+ // result.zone: 'noop' (duplicate) | 'add' (new) | 'borderline' (LLM decided)
60
43
  ```
61
44
 
62
- ### 4. Verify
45
+ ## VectorDB Providers
46
+
47
+ Two providers, same SQL functions, different transport:
63
48
 
64
- Use `memory_audit` to check health, then `memory_store` to create your first memory.
49
+ | Provider | Connection | Transport | When to use |
50
+ |----------|-----------|-----------|-------------|
51
+ | Supabase | `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` | PostgREST (HTTP) | Easiest setup, free tier |
52
+ | Postgres | `DATABASE_URL` | pg wire protocol | RDS, Aurora, Docker, self-hosted |
65
53
 
66
- ---
54
+ Auto-detected from environment variables. Or explicit:
55
+
56
+ ```typescript
57
+ import { getVectorDB } from '@traqr/memory'
67
58
 
68
- ## 10 MCP Tools
59
+ const db = getVectorDB({ type: 'postgres' })
60
+ await db.ping() // true
61
+ ```
69
62
 
70
- | Tool | Description |
71
- |------|-------------|
72
- | `memory_store` | Remember something. Only content required — everything else auto-derived. |
73
- | `memory_search` | Search memories by meaning. Returns summaries. |
74
- | `memory_read` | Expand a memory by ID. Full content + version history. |
75
- | `memory_enhance` | Deepen understanding. Creates connected memories via triage pipeline. |
76
- | `memory_browse` | Navigate by facet. Domain > category > summaries. Zero embedding cost. |
77
- | `memory_context` | Load task-relevant context — principles, preferences, gotchas. |
78
- | `memory_pulse` | Batch: capture multiple learnings + search + update in one call. |
79
- | `memory_audit` | System health, stats, quality metrics. |
80
- | `memory_archive` | Archive stale content that was once correct. |
81
- | `memory_forget` | Forget incorrect or harmful content permanently. |
63
+ For raw Postgres, install the `pg` package: `npm install pg`
82
64
 
83
- ## What's Inside
65
+ ## Embedding Providers
84
66
 
85
- **Schema** (created by `setup.sql`):
86
- - `traqr_memories` — content, embeddings, lifecycle, dual tsvectors
87
- - `memory_relationships` — graph edges between memories
88
- - `memory_entities` — extracted entities with embeddings
89
- - `memory_entity_links` — memory-to-entity junction table
90
- - 12+ indexes including partial HNSW, BM25 GIN, lifecycle
91
- - 10+ RPC functions for search, BM25, temporal, graph, confidence decay
67
+ | Provider | Env Var | Model | Dimensions |
68
+ |----------|---------|-------|-----------|
69
+ | OpenAI | `OPENAI_API_KEY` | text-embedding-3-small | 1536 |
70
+ | Gemini | `GOOGLE_API_KEY` | gemini-embedding-001 | 1536 |
71
+ | Bedrock | `EMBEDDING_PROVIDER=bedrock` + AWS creds | amazon.nova-embed-v1:0 | 1536 |
72
+ | Ollama | `EMBEDDING_PROVIDER=ollama` | nomic-embed-text | 768 |
73
+ | None | `EMBEDDING_PROVIDER=none` | — | 0 (BM25 only) |
92
74
 
93
- **Intelligence** (in the TypeScript package):
94
- - Multi-strategy retrieval: semantic + BM25 > RRF fusion > optional Cohere rerank
95
- - 3-zone cosine triage: NOOP (>=0.90), ADD (<0.60), borderline (GPT-4o-mini decision)
96
- - Type-aware lifecycle: facts invalidate, preferences supersede, patterns coexist
97
- - Entity extraction: multi-signal canonicalization (name > ILIKE > embedding)
98
- - Quality gate: 3-layer ingestion filter prevents noise
75
+ Set `EMBEDDING_PROVIDER` explicitly, or it auto-detects from available API keys.
99
76
 
100
- ## Graceful Degradation
77
+ ```typescript
78
+ import { getEmbeddingProvider } from '@traqr/memory'
101
79
 
102
- | Missing | Behavior |
103
- |---------|----------|
104
- | No embedding API key | Entities use name matching. BM25 keyword search works. No vector search. |
105
- | No COHERE_API_KEY | Search uses RRF scores instead of Cohere rerank. |
80
+ const ep = getEmbeddingProvider()
81
+ console.log(ep.provider, ep.model, ep.dimensions)
82
+ // 'openai', 'text-embedding-3-small', 1536
83
+ ```
106
84
 
107
- ## TypeScript Library API
85
+ ## Key Exports
108
86
 
109
87
  ```typescript
110
- import { storeMemory, searchMemories, triageAndStore } from '@traqr/memory'
88
+ // High-level operations
89
+ import {
90
+ storeMemory, searchMemoriesV2, getMemory, updateMemory, deleteMemory,
91
+ triageAndStore, storeWithDedup, archiveMemory, remember, recall,
92
+ } from '@traqr/memory'
111
93
 
112
- // Store a memory
113
- await storeMemory({ content: 'Always use bun', sourceType: 'manual' })
94
+ // VectorDB layer
95
+ import { getVectorDB, resetVectorDB } from '@traqr/memory'
96
+ import type { VectorDBProvider, Memory, MemorySearchResult } from '@traqr/memory'
97
+
98
+ // Embeddings
99
+ import { generateEmbedding, getEmbeddingProvider } from '@traqr/memory'
100
+ import type { EmbeddingProvider, EmbeddingResult } from '@traqr/memory'
114
101
 
115
- // Search by meaning
116
- const results = await searchMemories('package manager', { limit: 5 })
102
+ // Configuration
103
+ import { configureMemory, getMemoryConfig } from '@traqr/memory'
117
104
 
118
- // Store with triage (dedup + edges + LLM borderline)
119
- const result = await triageAndStore({ content: '...', sourceType: 'session' })
120
- // result.zone: 'noop' | 'add' | 'borderline'
105
+ // Auto-derive (extracts domain, category, topic, tags from content)
106
+ import { deriveAll } from '@traqr/memory'
107
+
108
+ // Multi-strategy retrieval internals
109
+ import { reciprocalRankFusion, detectStrategies } from '@traqr/memory'
121
110
  ```
122
111
 
123
- ## Environment Variables
112
+ ## Database Setup
113
+
114
+ Run `setup.sql` on your Postgres 15+ database (pgvector required):
124
115
 
125
- | Variable | Required | Description |
126
- |----------|----------|-------------|
127
- | `DATABASE_URL` or `SUPABASE_URL` | Yes | Postgres connection |
128
- | `SUPABASE_SERVICE_ROLE_KEY` | Supabase only | Service role key |
129
- | `OPENAI_API_KEY` | Recommended | OpenAI embeddings |
130
- | `GOOGLE_API_KEY` | Alternative | Gemini Embedding 2 (free) |
131
- | `COHERE_API_KEY` | No | Cohere Rerank (quality boost) |
116
+ ```bash
117
+ # Supabase: paste into SQL Editor
118
+ # Postgres: psql $DATABASE_URL -f setup.sql
119
+ # Docker:
120
+ docker run -d --name traqrdb -e POSTGRES_PASSWORD=postgres -p 5432:5432 pgvector/pgvector:pg16
121
+ psql postgresql://postgres:postgres@localhost:5432/postgres -f node_modules/traqr-memory-mcp/setup.sql
122
+ ```
132
123
 
133
124
  ## License
134
125
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@traqr/memory",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "Persistent memory for AI agents. Multi-strategy retrieval (semantic + BM25 + RRF), 3-zone cosine triage, type-aware lifecycle, entity canonicalization. Postgres + pgvector.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",