a2a-memory 0.10.0 → 0.10.1

package/README.md

@@ -1,24 +1,34 @@
 # @a2a/memory - Persistent AI Memory for Claude Code
 
-> v0.6.0 — Local-first memory system with server sync, team collaboration, and intelligent search
+> v0.10.0 — Local-first memory system with realtime context injection, semantic search, and team collaboration
 
-Persistent AI memory for Claude Code. Automatically captures, stores, and retrieves knowledge across coding sessions.
+Persistent AI memory for Claude Code. Automatically captures, stores, and retrieves knowledge across coding sessions with realtime prompt-level memory injection.
 
 ## Features
 
 ### Core Capabilities
+- **Realtime Context Injection** - Inject relevant memories on every prompt via UserPromptSubmit hook
 - **Session Extraction** - Extract memories from Claude Code sessions (JSONL parsing)
 - **Local-First DB** - SQLite with FTS5 full-text search + vector similarity
-- **Auto-Capture Hooks** - Claude Code hooks for automatic memory capture
-- **Context Injection** - Inject relevant memories at session start (hybrid search)
+- **Auto-Capture Hooks** - 5 Claude Code hooks for automatic memory lifecycle
 - **Hybrid Search** - FTS + Vector + Recency ranking (Reciprocal Rank Fusion)
+- **Adaptive RAG Router** - Query complexity classification (simple/semantic/complex)
+- **Cross-Encoder Reranker** - Precision re-ranking with ms-marco-MiniLM
 - **Lifecycle Management** - Quality scoring, TTL-based cleanup, memory tiering (Hot/Warm/Cold)
 
 ### AI & Embeddings
+- **E5 Embedding (384D)** - Local semantic embedding via e5-small-v2 (ONNX, ~16ms/query)
+- **Local TF-IDF (64D)** - Lightweight hash-based embedding (fallback)
+- **OpenAI Embedding (1536D)** - Cloud embedding via OpenAI API
 - **LLM Integration** - AI-powered extraction and classification (OpenAI, Anthropic)
-- **Embeddings** - Local TF-IDF (64D) or OpenAI (1536D) embeddings
 - **Vector Quantization** - Float32 and Int8 scalar quantization for compression
 
+### Intelligence
+- **4-Way Dedup (Mem0 Pattern)** - ADD/UPDATE/DELETE/NOOP for memory deduplication
+- **Skill Crystallization** - Repeated patterns auto-crystallize into reusable skills
+- **Proficiency Tracking** - ACT-R cognitive model for skill level tracking
+- **PreCompact Checkpoint** - Preserve critical context before context window compression
+
 ### Team & Sync
 - **Server Sync** - Synchronize with A2A server via REST API
 - **Team Collaboration** - Share memories across team members (CRDT vector clocks)
@@ -28,10 +38,10 @@ Persistent AI memory for Claude Code. Automatically captures, stores, and retrie
 
 ### Developer Experience
 - **CLAUDE.md Sync** - Sync CLAUDE.md sections to memory DB
-- **CLI (16 commands)** - Full command-line interface for all operations
+- **CLI (19 commands)** - Full command-line interface for all operations
 - **Logging** - JSON Lines hook logs with rotation and level filtering
 - **i18n** - Internationalization support (Korean, English)
-- **Sensitive Info Filter** - Auto-redaction of API keys, passwords, tokens (21 patterns)
+- **Sensitive Info Filter** - Auto-redaction of API keys, passwords, tokens (21+ patterns)
 
 ## Quick Start
 
@@ -74,18 +84,24 @@ a2a-memory health
 | `a2a-memory cleanup` | Remove low-quality/expired memories | `--dry-run` |
 | `a2a-memory health` | System health check (DB, config, logs) | `--verbose` |
 | `a2a-memory claude-sync` | Sync CLAUDE.md to memory DB | `--dry-run`, `--force` |
+| `a2a-memory skill` | Manage crystallized skills | `list`, `inspect <id>` |
+| `a2a-memory proficiency list` | Show proficiency levels for all skills | - |
+| `a2a-memory proficiency inspect <id>` | Detailed proficiency analysis | - |
+| `a2a-memory proficiency simulate` | Simulate proficiency scenarios | - |
 
 ## Architecture
 
 ### 1. Claude Code Hooks
 
-After `a2a-memory setup`, three hooks are registered:
+After `a2a-memory setup`, five hooks are registered:
 
-| Hook | Trigger | Action | Features |
-|------|---------|--------|----------|
-| **SessionStart** | Session begins | Injects relevant memories via hybrid search | Team memory pull, context injection |
-| **PostToolUse** | After Write/Edit/Bash | Auto-captures significant actions | Significance scoring, sensitive info filtering |
-| **SessionEnd** | Session ends | Extracts memories + optional team sync | Session summarization, team push, scheduled sync |
+| Hook | Trigger | Action | Performance |
+|------|---------|--------|-------------|
+| **SessionStart** | Session begins | Injects relevant memories via hybrid search | ~200ms |
+| **PostToolUse** | After Write/Edit/Bash/Read/Grep/Glob | Auto-captures significant actions + dedup check | ~50ms |
+| **UserPromptSubmit** | Every user prompt | Realtime FTS search + context injection | p50 < 30ms |
+| **PreCompact** | Before context compression | Extracts key decisions/progress/TODOs as checkpoints | ~100ms |
+| **SessionEnd** | Session ends | Extracts memories + team sync + skill evaluation | ~500ms |
 
 ### 2. Memory Extraction
 
@@ -98,8 +114,10 @@ Parses `~/.claude/projects/<project>/<session>.jsonl` files and extracts:
 | `decision` | Architectural decisions with reasoning |
 | `project_knowledge` | Project context and rules |
 | `convention` | Development conventions and preferences |
+| `learning` | Learned techniques and insights |
+| `skill` | Crystallized reusable skills |
 
-### 3. Hybrid Search
+### 3. Hybrid Search with Adaptive RAG
 
 Three-signal Reciprocal Rank Fusion (RRF):
 
@@ -108,10 +126,31 @@ Score = w1 * FTS_rank + w2 * Vector_similarity + w3 * Recency_score
 ```
 
 - **FTS**: SQLite FTS5 full-text search
-- **Vector**: TF-IDF (local, 64D) or OpenAI (1536D) embeddings
+- **Vector**: E5 (384D), TF-IDF (64D), or OpenAI (1536D) embeddings
 - **Recency**: Time decay scoring
+- **Skill Boost**: 1.5x weight for crystallized skill memories
+
+**Adaptive Router** classifies query complexity:
+- `simple` (1-2 keywords) → FTS only (< 5ms)
+- `semantic` (questions, descriptions) → FTS + Vector (< 30ms)
+- `complex` (code patterns, errors) → FTS + Vector + Reranker (< 100ms)
+
+**Cross-Encoder Reranker** (optional):
+- ms-marco-MiniLM-L-6-v2 for precision re-ranking
+- top-20 → top-5 refinement
+
+### 4. Memory Deduplication (Mem0 Pattern)
+
+4-Way decision for every new memory:
 
-### 4. Storage & Indexing
+| Action | Condition | Result |
+|--------|-----------|--------|
+| `ADD` | No similar memory exists | Create new |
+| `UPDATE` | Similarity > 0.8 | Merge with existing |
+| `DELETE` | New info invalidates old | Replace |
+| `NOOP` | Similarity > 0.95 | Skip (exact duplicate) |
+
+### 5. Storage & Indexing
 
 - **SQLite database** at `~/.a2a/memory.db`
   - FTS5 full-text search index
@@ -131,35 +170,56 @@ Config file: `~/.a2a/config.json`
   "mode": "local",
   "autoCapture": {
     "enabled": false,
-    "triggers": ["Write", "Edit", "Bash"],
+    "triggers": ["Write", "Edit", "Bash", "Read", "Grep", "Glob"],
     "significanceThreshold": 0.6
   },
   "autoInject": {
     "enabled": true,
-    "maxMemories": 5,
+    "maxMemories": 10,
     "maxTokens": 2000
   },
+  "realtimeInject": {
+    "enabled": true,
+    "maxMemories": 3,
+    "maxTokens": 1000,
+    "cacheSize": 20,
+    "cacheTTLSeconds": 60,
+    "timeoutMs": 100
+  },
+  "embedding": {
+    "enabled": false,
+    "provider": "local",
+    "dimensions": 64
+  },
+  "lifecycle": {
+    "ttlDays": 90,
+    "maxMemories": 1000,
+    "cleanupOnSessionEnd": false,
+    "qualityThreshold": 0.3
+  },
+  "skillConversion": {
+    "enabled": false,
+    "evaluationInterval": 5,
+    "minRepetitions": 3,
+    "similarityThreshold": 0.85,
+    "minConfidence": 0.7
+  },
+  "proficiency": {
+    "enabled": true,
+    "levelFormula": "activation",
+    "maxLevel": 10
+  },
   "autoSync": {
     "enabled": false,
     "pushOnSessionEnd": true,
     "pullOnSessionStart": true,
-    "timeoutMs": 10000,
+    "timeoutMs": 30000,
     "intervalMs": 1800000
   },
   "db": {
     "path": "~/.a2a/memory.db",
     "maxSizeMB": 100
   },
-  "embedding": {
-    "provider": "local",
-    "dimensions": 64
-  },
-  "lifecycle": {
-    "enabled": true,
-    "maxMemories": 10000,
-    "ttlDays": { "working": 7, "episodic": 90 },
-    "minQualityScore": 0.3
-  },
   "logging": {
     "enabled": false,
     "level": "info",
@@ -170,6 +230,24 @@ Config file: `~/.a2a/config.json`
 }
 ```
 
+### Embedding Providers
+
+| Provider | Dimensions | Latency | Install |
+|----------|-----------|---------|---------|
+| `local` (TF-IDF) | 64 | < 1ms | Built-in |
+| `e5` (e5-small-v2) | 384 | ~16ms | `npm install @huggingface/transformers` |
+| `openai` | 1536 | ~100ms | Requires API key |
+
+```bash
+# Enable E5 embeddings
+a2a-memory config set embedding.enabled true
+a2a-memory config set embedding.provider e5
+a2a-memory config set embedding.dimensions 384
+
+# Generate embeddings for existing memories
+a2a-memory embed generate
+```
+
 ### Server Sync
 
 ```bash
@@ -223,7 +301,13 @@ import {
 
   // Search
   HybridRanker,
+  AdaptiveRouter,
+  CrossEncoderReranker,
   createEmbeddingProvider,
+  E5EmbeddingProvider,
+
+  // Extraction
+  DedupManager,
 
   // Sync
   A2AClient,
@@ -239,6 +323,10 @@ import {
   encryptContent,
   decryptContent,
 
+  // Proficiency
+  ACTREngine,
+  ProficiencyTracker,
+
   // Claude.md
   syncClaudeMd,
 } from 'a2a-memory';
@@ -254,11 +342,21 @@ db.createMemory({
   tags: ['auth', 'jwt'],
 });
 
-// Hybrid search with embeddings
-const provider = createEmbeddingProvider({ provider: 'local', dimensions: 64 });
+// Hybrid search with E5 embeddings
+const provider = createEmbeddingProvider({ provider: 'e5', dimensions: 384, enabled: true });
 const ranker = new HybridRanker(db, provider);
 const ranked = await ranker.search('auth error', { limit: 5 });
 
+// Adaptive RAG routing
+const router = new AdaptiveRouter();
+const route = router.classify('how to fix JWT token expiration?');
+// → { complexity: 'semantic', strategy: 'fts+vector' }
+
+// Memory deduplication
+const dedup = new DedupManager(db);
+const decision = await dedup.decide(newContent, existingMemories);
+// → { action: 'UPDATE', targetId: 'mem_123', reason: '...' }
+
 // Server sync
 const client = new A2AClient({
   serverUrl: 'https://a2a-api-production-8d17.up.railway.app',
@@ -268,41 +366,24 @@ const sync = new MemorySynchronizer(db, client);
 await sync.push();
 await sync.pull();
 
-// Scheduled sync
-const scheduler = new SyncScheduler(sync, { intervalMs: 1800000 });
-scheduler.start();
-
-// Team collaboration
-const teamSync = new TeamSynchronizer(db, client, 'team-id');
-await teamSync.pushTeamMemories();
-await teamSync.pullTeamMemories();
-
-// Lifecycle management
-await cleanupMemories(db, { ttlDays: 90, minQualityScore: 0.3 });
-await rebalanceTiers(db);
-
-// Anthropic Memory API adapter (for future integration)
+// Anthropic Memory API adapter
 import { toAnthropicFormat, fromAnthropicFormat } from 'a2a-memory';
 
 const memory = db.getMemory('mem_123');
 const anthropicFormat = toAnthropicFormat(memory);
-// → { id, content, type: 'user_preference' | 'learned_info' | 'conversation_context', ... }
-
-const anthropicMemory = { id: '...', content: '...', type: 'learned_info', ... };
-const a2aInput = fromAnthropicFormat(anthropicMemory);
-db.createMemory(a2aInput);
 ```
 
 ## Security
 
 ### Sensitive Information Protection
 
-Automatically filters 21 patterns including:
+Automatically filters 21+ patterns including:
 - Cloud provider keys (AWS, Google, Azure)
 - API keys and secrets (OpenAI, Stripe, GitHub)
 - Database connection strings
-- Private keys and certificates (RSA, EC, DSA)
+- Private keys and certificates (RSA, EC, DSA, OPENSSH)
 - JWT tokens and session cookies
+- Service tokens (Slack, Discord, npm, PyPI)
 - Personal identifiable information (Korean SSN, Business registration)
 
 ### Encryption
@@ -330,6 +411,7 @@ Fallback: Encrypted file storage at `~/.a2a/credentials.enc`
 
 - Node.js >= 18.0.0
 - Claude Code (for hooks integration)
+- `@huggingface/transformers` (optional, for E5 embeddings)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "a2a-memory",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Persistent AI memory for Claude Code - Session extraction, local DB, and hook automation",
   "type": "module",
   "main": "dist/index.js",