​

Version 3.1.0 - Collective Best Practices & Intelligent Memory

​

Overview

​

Key Features

​

Claude Code Plugin

• Native MCP Integration: All plugged.in tools, knowledge base, memory, and notifications available directly in Claude Code
• Zero Configuration: Add via .mcp.json with just your API key
• Memory Lifecycle Hooks: Automatic session management — start on session begin, Z-reports on end
• Pre-Compaction Context: Relevant memories injected before context window compaction
• 9 Built-in Skills: Memory search, extraction, workflow, status, RAG context, setup, and more
• 2 Agents: Memory curator for classification, focus assistant for working set management
• CBP Post-Error Suggestions: Automatic community pattern suggestions after tool errors

​

Collective Best Practices (CBP)

• Privacy-Preserving Pattern Aggregation: Learns from all users while protecting individual data
• HMAC-SHA256 Pattern Hashing: Patterns normalized and hashed — never stored in plaintext
• k-Anonymity (k>=3): Patterns only shared when observed by 3+ unique profiles
• Success Rate Tracking: Community patterns ranked by effectiveness
• Contextual Injection: Relevant CBP patterns automatically suggested during sessions
• Feedback Loop: Users can confirm or reject CBP suggestions to improve quality

​

Concentric Memory Rings

• Fresh Memory: Observation buffer with auto-classification and embedding
• Procedures: Repeatable workflows, how-tos, step-by-step guides
• Practice/Habits: Successful patterns reinforced through repetition
• Long-term: Validated insights requiring success_score >= 0.7
• Shocks: Critical failures that bypass decay — never forgotten

​

Intelligent Forgetting (Decay Engine)

​

Shared Vector Infrastructure (pgvector)

• PostgreSQL pgvector Extension: Native vector search without external services
• HNSW Indexing: High-recall cosine distance similarity search
• 1536-Dimension Embeddings: Using text-embedding-3-small via OpenAI or Google Gemini
• AI Provider Abstraction: Automatic routing between OpenAI and Google embedding providers

​

Progressive Retrieval (3-Layer)

• Layer 1 (Search): Returns content_essence or content_summary (50-150 tokens each)
• Layer 2 (Timeline): Adds temporal context — when, which session, related observations
• Layer 3 (Full Details): Returns content_full only for selected memories

​

Z-Reports (Session Summaries)

• Summary text with key observations
• Decisions made and tools used
• Success rate calculation (0.0-1.0)
• Z-reports eligible for promotion to long-term memory

​

New MCP Tools

​

Database Changes

• memory_sessions — Session tracking with Z-reports
• fresh_memory — Observation buffer with vector embeddings
• memory_ring — Unified long-term store for all ring types
• gut_patterns — Collective wisdom (NOT profile-scoped, k-anonymous)

​

Migration Notes

​

Upgrade Steps

# Pull latest and install
git pull origin main
pnpm install

# Generate and apply migrations
pnpm db:generate
pnpm db:migrate

# The migration automatically enables the pgvector extension

​

New Environment Variables (Optional)

# Memory Configuration
MEMORY_EMBEDDING_MODEL=text-embedding-3-small
MEMORY_DECAY_CRON_ENABLED=true
MEMORY_ANALYTICS_BATCH_SIZE=50
MEMORY_EMBEDDING_DIMENSION=1536

​

Security

• 6 rounds of code review hardening (PR #138)
• HMAC-SHA256 privacy for collective patterns
• k-anonymity threshold enforcement
• Advisory lock-based race condition prevention
• Transaction safety for all memory operations

​

What’s Next

• Full memory UI (Fresh, Long-term, Procedures tabs)
• Advanced analytics dashboard
• Cross-agent memory sharing
• Memory export/import