a2a-memory

v0.11.6

Published

3 days ago

Persistent AI memory for Claude Code - Session extraction, local DB, and hook automation

0High
0Medium
0Low

parksw02

claude claude-code memory ai plugin session knowledge

@a2a/memory - Persistent AI Memory for Claude Code

v0.11.6 — Local-first memory system with realtime context injection, semantic search, memory-file linking, and team collaboration

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 - 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), CleanupScheduler
Auto Memory Sync - PostToolUse Hook에서 Claude memory 파일 자동 동기화

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)
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)
E2E Encryption - AES-256-GCM encryption for sensitive content
Scheduled Sync - Automatic periodic sync with configurable interval
OS Keychain - Secure API key storage (macOS/Linux/Windows)

Developer Experience

CLAUDE.md Sync - Sync CLAUDE.md sections to memory DB
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)

Quick Start

# Install globally
npm install -g a2a-memory

# Initialize (creates DB + registers Claude Code hooks)
a2a-memory setup

# Extract memories from existing sessions
a2a-memory extract --limit 20

# Check status
a2a-memory status

# Search memories
a2a-memory search "authentication error"

# Health check
a2a-memory health

CLI Commands

| Command | Description | Options | |---------|-------------|---------| | a2a-memory setup | Initialize plugin, create DB, register hooks | - | | a2a-memory status | Show memory count, DB size, category breakdown | - | | a2a-memory extract | Extract memories from session files | --limit <n>, --project <path> | | a2a-memory search <query> | Hybrid search across all memories | --limit <n>, --category <cat> | | a2a-memory list | List memories with category/tier filters | --category, --tier, --limit | | a2a-memory add | Manually add a memory (interactive) | - | | a2a-memory edit <id> | Edit an existing memory (interactive) | - | | a2a-memory rm <id> | Delete a memory | - | | a2a-memory config | View and modify configuration | get <key>, set <key> <value> | | a2a-memory sync | Synchronize with A2A server | --push, --pull, --watch, --interval <ms> | | a2a-memory team | Team memory management | join <teamId>, sync, members | | a2a-memory embed | Manage embeddings | generate, stats | | 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, five hooks are registered:

| 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 + Claude memory file sync | ~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

Parses ~/.claude/projects/<project>/<session>.jsonl files and extracts:

| Category | Examples | |----------|---------| | error_solution | Error + resolution pairs | | code_pattern | Repeated tool usage patterns | | 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 with Adaptive RAG

Three-signal Reciprocal Rank Fusion (RRF):

Score = w1 * FTS_rank + w2 * Vector_similarity + w3 * Recency_score

FTS: SQLite FTS5 full-text search
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:

| 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
- Vector embeddings table (with quantization support)
- WAL mode for concurrent access
- Sync status tracking with CRDT vector clocks
Memory Tiering: Hot (0-7 days), Warm (8-30 days), Cold (30+ days)
Vector Quantization: Float32 (50% reduction), Int8 (75% reduction)
E2E Encryption: AES-256-GCM with PBKDF2 key derivation

Configuration

Config file: ~/.a2a/config.json

{
  "mode": "local",
  "autoCapture": {
    "enabled": false,
    "triggers": ["Write", "Edit", "Bash", "Read", "Grep", "Glob"],
    "significanceThreshold": 0.6
  },
  "autoInject": {
    "enabled": true,
    "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": 30000,
    "intervalMs": 1800000
  },
  "db": {
    "path": "~/.a2a/memory.db",
    "maxSizeMB": 100
  },
  "logging": {
    "enabled": false,
    "level": "info",
    "outputDir": "~/.a2a/logs",
    "maxFileSizeMB": 10,
    "maxFiles": 3
  }
}

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 |

# 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

# Configure server
a2a-memory config set server.url https://your-a2a-server.com
a2a-memory config set server.apiKey your-api-key

# One-time sync
a2a-memory sync --push    # local -> remote
a2a-memory sync --pull    # remote -> local

# Continuous sync (every 30 min)
a2a-memory sync --watch
a2a-memory sync --watch --interval 60000  # every 60s

Team Mode

# Join a team
a2a-memory team join my-team

# Sync team memories
a2a-memory team sync

# List team members
a2a-memory team members

CLAUDE.md Sync

# Sync CLAUDE.md sections to memory DB
a2a-memory claude-sync

# Preview without writing
a2a-memory claude-sync --dry-run

# Force re-sync
a2a-memory claude-sync --force

Programmatic API

import {
  // Core
  MemoryDatabase,
  ConfigManager,
  extractMemories,

  // Search
  HybridRanker,
  AdaptiveRouter,
  CrossEncoderReranker,
  createEmbeddingProvider,
  E5EmbeddingProvider,

  // Extraction
  DedupManager,

  // Sync
  A2AClient,
  MemorySynchronizer,
  TeamSynchronizer,
  SyncScheduler,

  // Lifecycle
  cleanupMemories,
  rebalanceTiers,

  // Encryption
  encryptContent,
  decryptContent,

  // Proficiency
  ACTREngine,
  ProficiencyTracker,

  // Claude.md
  syncClaudeMd,
} from 'a2a-memory';

// Database operations
const db = new MemoryDatabase('~/.a2a/memory.db');
db.initialize();

db.createMemory({
  content: 'JWT tokens expire after 30 minutes',
  category: 'convention',
  tier: 'semantic',
  tags: ['auth', 'jwt'],
});

// 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',
  apiKey: 'your-api-key',
});
const sync = new MemorySynchronizer(db, client);
await sync.push();
await sync.pull();

// Anthropic Memory API adapter
import { toAnthropicFormat, fromAnthropicFormat } from 'a2a-memory';

const memory = db.getMemory('mem_123');
const anthropicFormat = toAnthropicFormat(memory);

Security

Sensitive Information Protection

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, OPENSSH)
JWT tokens and session cookies
Service tokens (Slack, Discord, npm, PyPI)
Personal identifiable information (Korean SSN, Business registration)

Encryption

E2E Encryption (opt-in via config):

a2a-memory config set autoSync.encryption.enabled true

Algorithm: AES-256-GCM
Key derivation: PBKDF2-HMAC-SHA256 (600,000 iterations)
Storage: OS keychain integration (macOS, Linux, Windows)
Scope: Content + embeddings encrypted before transmission

API Key Storage

Uses OS-native secure storage:

macOS: Keychain (security command)
Linux: Secret Service API (secret-tool)
Windows: Credential Manager (via node-keytar)

Fallback: Encrypted file storage at ~/.a2a/credentials.enc

Requirements

Node.js >= 18.0.0
Claude Code (for hooks integration)
@huggingface/transformers (optional, for E5 embeddings)

License

MIT