> ## Documentation Index > Fetch the complete documentation index at: https://docs.plugged.in/llms.txt > Use this file to discover all available pages before exploring further. # Memory & Intelligent Knowledge > Human cognition-inspired memory system with concentric rings, collective best practices, and persistent clipboard storage # Memory & Intelligent Knowledge The Memory system in plugged.in provides two complementary capabilities: an **Intelligent Memory** architecture inspired by human cognition (v3.1.0+), and a **Persistent Clipboard** for key-value storage between tool invocations. Together they give AI agents the ability to learn, remember, and share knowledge across sessions. ## Overview Five memory ring types inspired by how humans form and retain knowledge Privacy-preserving community wisdom with k-anonymity Token-based decay engine that compresses memories over time End-of-session summaries that capture key observations and decisions 3-layer retrieval system optimized for token efficiency Named and indexed key-value storage with TTL expiration *** ## Intelligent Memory System Intelligent Memory was introduced in v3.1.0. It requires the pgvector PostgreSQL extension, which is automatically enabled during migration. ### Concentric Memory Rings The memory architecture uses five ring types that mirror how human cognition processes and stores information: **Observation buffer** -- the entry point for all new memories. * Raw observations recorded during active sessions * Auto-classified into appropriate ring types by the memory curator agent * Vector embeddings generated for semantic search * Short-lived unless promoted to a higher ring **Example**: "User prefers TypeScript over JavaScript for new projects" **Repeatable workflows** -- step-by-step guides and how-tos. * Multi-step processes that can be replayed * Versioned as they are refined over time * Higher retention priority than general observations **Example**: "Deploy to staging: 1) Run tests 2) Build Docker image 3) Push to registry 4) Apply k8s manifests" **Successful patterns** -- reinforced through repetition. * Patterns that have been observed multiple times * Strengthened each time the pattern succeeds * Weakened when the pattern fails **Example**: "Always run `pnpm db:generate` before `pnpm db:migrate` when changing schema" **Validated insights** -- requires `success_score >= 0.7` to enter. * High-confidence knowledge that has proven its value * Slower decay rate than other rings * Core knowledge base for the agent **Example**: "The pluggedin-app uses Drizzle ORM with varchar-based enums, not pgEnum" **Critical failures** -- never forgotten. * Catastrophic errors, data loss events, security incidents * Bypass the decay engine entirely * Always surfaced when relevant context is detected **Example**: "NEVER run `git push --force` to main -- caused production data loss on 2026-01-15" ### Intelligent Forgetting (Decay Engine) Memories progressively compress over time, preserving essential knowledge while freeing token budget: | Stage | Tokens | Time to Next Stage | Description | | -------------- | ------ | ------------------ | -------------------------------------- | | **FULL** | \~500 | 7 days | Complete observation with all context | | **COMPRESSED** | \~250 | 30 days | Key details preserved, context trimmed | | **SUMMARY** | \~150 | 90 days | Single paragraph summary | | **ESSENCE** | \~50 | 365 days | One-sentence core insight | | **FORGOTTEN** | 0 | Deleted | Removed from storage | **Decay exceptions**: * **Shocks** never decay regardless of age * **Frequently accessed** memories decay slower (access resets the timer) * **Low success score** memories decay faster ### Progressive Retrieval (3-Layer) Token-efficient memory access that only loads what you need: Returns `content_essence` or `content_summary` for each match (50-150 tokens per result). Ideal for scanning many memories quickly. Adds temporal context -- when the memory was created, which session, and related observations. Useful for understanding sequence of events. Returns `content_full` for specifically selected memories. Only used when you need the complete context for a particular memory. ### Z-Reports (Session Summaries) Inspired by retail Z-reports (end-of-day cash register summaries), Z-reports capture what happened during each session: * **Summary text** with key observations and outcomes * **Decisions made** during the session * **Tools used** and their results * **Success rate** calculation (0.0 - 1.0) * Z-reports with high success scores are eligible for **promotion to long-term memory** ### Vector Search Infrastructure Memory uses PostgreSQL pgvector for semantic search: * **HNSW Indexing**: High-recall approximate nearest neighbor search * **1536-Dimension Embeddings**: Generated via `text-embedding-3-small` (OpenAI) or Gemini (Google) * **Cosine Distance**: Similarity metric for comparing memory embeddings * **AI Provider Abstraction**: Automatic routing between available embedding providers *** ## Collective Best Practices (CBP) CBP is a privacy-preserving system that learns effective patterns from across the community and suggests them when relevant. ### How It Works ``` User Action (e.g., fix a bug) | v Pattern Extracted & Normalized | v HMAC-SHA256 Hash (never stored in plaintext) | v k-Anonymity Check (k >= 3 unique profiles?) | v If yes: Pattern available for suggestions If no: Pattern stays private ``` ### Privacy Guarantees Patterns are normalized and hashed before storage. The original pattern text is never stored in the collective pool. Patterns are only surfaced as suggestions when observed independently by 3 or more unique profiles. ### Feedback Loop When a CBP pattern is suggested, users can: * **Confirm**: Increases the pattern's success rate * **Reject**: Decreases the pattern's success rate and suppresses future suggestions This creates a self-improving knowledge base where the most effective patterns rise to the top. *** ## Memory MCP Tools ### Session & Observation Tools | Tool | Description | | -------------------------------- | ------------------------------------------------------- | | `pluggedin_memory_session_start` | Start a memory session for the current interaction | | `pluggedin_memory_session_end` | End the session and trigger Z-report generation | | `pluggedin_memory_observe` | Record an observation during an active session | | `pluggedin_memory_search` | Search memories using progressive layer 1 retrieval | | `pluggedin_memory_details` | Get full memory details (layer 3) for a specific memory | ### Collective Best Practices Tools | Tool | Description | | ------------------------ | ----------------------------------------------------- | | `pluggedin_cbp_query` | Query collective best practices for relevant patterns | | `pluggedin_cbp_feedback` | Submit feedback (confirm/reject) on a CBP suggestion | *** ## Persistent Clipboard The Clipboard provides persistent key-value storage that MCP tools and AI agents can use to share data between tool invocations. With support for both named (semantic keys) and indexed (array-like) access patterns, it enables sophisticated data persistence workflows. ### Access Patterns **How it works**: Store data with semantic keys for direct retrieval. **Example Keys**: `user_preferences`, `last_search_results`, `conversation_context` **Best for**: * Configuration and preferences * Caching frequently used data * Sharing state between tools * Key-based lookups ```typescript theme={null} // Set a named entry await clipboard.set({ name: "user_preferences", value: JSON.stringify({ theme: "dark", lang: "en" }), contentType: "application/json" }); // Get by name const prefs = await clipboard.get({ name: "user_preferences" }); ``` **How it works**: Push data to a stack and retrieve by index (0 = most recent). **Example Use Cases**: Processing queues, undo stacks, sequential data **Best for**: * LIFO (Last-In-First-Out) workflows * Undo/redo operations * Processing pipelines * Temporary data storage ```typescript theme={null} // Push to stack await clipboard.push({ value: "Step 1 result", contentType: "text/plain" }); // Pop most recent (index 0) const latest = await clipboard.pop(); ``` ### Clipboard MCP Tools #### Named Operations | Tool | Description | | ---------------------------- | ------------------------------------- | | `pluggedin_clipboard_set` | Set or update a named clipboard entry | | `pluggedin_clipboard_get` | Retrieve entry by name or index | | `pluggedin_clipboard_delete` | Delete a specific entry | | `pluggedin_clipboard_list` | List all clipboard entries | #### Stack Operations | Tool | Description | | -------------------------- | ------------------------------------ | | `pluggedin_clipboard_push` | Push value to indexed stack | | `pluggedin_clipboard_pop` | Pop and remove the most recent entry | ### Data Structure ```typescript theme={null} interface ClipboardEntry { uuid: string; // Unique identifier name?: string; // Semantic key (for named access) idx?: number; // Stack index (for indexed access) value: string; // Entry content contentType: string; // MIME type (default: "text/plain") encoding: "utf-8" | "base64" | "hex"; // Content encoding sizeBytes: number; // Content size in bytes visibility: "private" | "workspace" | "public"; createdByTool?: string; // Tool that created entry createdByModel?: string; // AI model that created entry source?: "ui" | "sdk" | "mcp"; // Entry source (auto-set) createdAt: Date; updatedAt: Date; expiresAt?: Date; // TTL expiration time } ``` ### Source Types | Source | Description | | ------ | --------------------------------------- | | `ui` | Created via the web interface (default) | | `sdk` | Created via one of the official SDKs | | `mcp` | Created via MCP proxy tools | The `source` field is automatically set based on how the entry was created. You cannot override this value. ### Content Types & Encoding For plain text and JSON data: ```typescript theme={null} { value: "Hello, World!", contentType: "text/plain", encoding: "utf-8" } ``` **Supported types**: `text/plain`, `application/json`, `text/markdown`, `text/html` For images, files, and binary data using base64: ```typescript theme={null} { value: "iVBORw0KGgoAAAANSUhEUgAA...", // base64 encoded contentType: "image/png", encoding: "base64" } ``` **Supported encodings**: `base64`, `hex` ### Usage Examples #### Sharing Data Between Tools ```typescript JavaScript SDK theme={null} import { PluggedInClient } from 'pluggedinkit'; const client = new PluggedInClient({ apiKey: 'your-api-key' }); // Tool A: Save search results await client.clipboard.set({ name: 'last_search_results', value: JSON.stringify({ results: [...], query: 'test' }), contentType: 'application/json', ttlSeconds: 3600 // Expire in 1 hour }); // Tool B: Retrieve and use results const entry = await client.clipboard.getByName('last_search_results'); const results = JSON.parse(entry.value); ``` ```python Python SDK theme={null} from pluggedinkit import PluggedInClient import json client = PluggedInClient(api_key="your-api-key") # Tool A: Save search results client.clipboard.set( name="last_search_results", value=json.dumps({"results": [...], "query": "test"}), content_type="application/json", ttl_seconds=3600 # Expire in 1 hour ) # Tool B: Retrieve and use results entry = client.clipboard.get(name="last_search_results") results = json.loads(entry.value) ``` ```go Go SDK theme={null} package main import ( "context" "encoding/json" pluggedinkit "github.com/veriteknik/pluggedinkit-go" ) func main() { client := pluggedinkit.NewClient("your-api-key") ctx := context.Background() // Tool A: Save search results data, _ := json.Marshal(map[string]interface{}{ "results": []string{...}, "query": "test", }) client.Clipboard.Set(ctx, &pluggedinkit.ClipboardSetRequest{ Name: "last_search_results", Value: string(data), ContentType: "application/json", TTLSeconds: 3600, }) // Tool B: Retrieve and use results entry, _ := client.Clipboard.GetByName(ctx, "last_search_results") var results map[string]interface{} json.Unmarshal([]byte(entry.Value), &results) } ``` #### Processing Pipeline with Stack ```typescript theme={null} // Step 1: Push initial data await client.clipboard.push({ value: JSON.stringify({ step: 1, data: 'raw input' }), contentType: 'application/json' }); // Step 2: Process and push result const step1 = await client.clipboard.pop(); const processed = processData(JSON.parse(step1.value)); await client.clipboard.push({ value: JSON.stringify({ step: 2, data: processed }), contentType: 'application/json' }); // Step 3: Final processing const step2 = await client.clipboard.pop(); const final = finalProcess(JSON.parse(step2.value)); ``` ### Limits & Quotas Maximum 2 MB per entry value 24 hours if not specified Standard API rate limits apply Entries isolated per profile *** ## Security & Isolation ### Access Control Clipboard entries are scoped to your profile and project. Never store sensitive credentials in clipboard entries. * **Profile Isolation**: Each profile has its own clipboard and memory namespace * **Project Scope**: Entries are associated with the current project * **CBP Privacy**: Collective patterns use HMAC-SHA256 hashing with k-anonymity * **Visibility Levels**: * `private`: Only accessible by you * `workspace`: Shared within your workspace * `public`: Accessible via API with authentication ### Data Protection * **Encryption**: Content encrypted at rest (AES-256-GCM) * **TTL Enforcement**: Automatic cleanup of expired entries * **Size Limits**: 2 MB maximum prevents abuse * **Sanitization**: Content validated before storage * **Transaction Safety**: All memory operations wrapped in database transactions *** ## Quick Start Navigate to **Memory** in the sidebar to view your memories and clipboard entries Use `pluggedin_memory_session_start` to begin tracking observations in your AI session Use `pluggedin_memory_observe` during your session to capture important patterns and decisions Use `pluggedin_memory_session_end` to generate a Z-report summarizing the session Use `pluggedin_memory_search` to find relevant past memories using natural language queries ## API Reference ### Memory Endpoints ```typescript theme={null} // Session management POST /api/memory/sessions // Start session PUT /api/memory/sessions/:id // End session / update // Observations POST /api/memory/observe // Record observation // Search & retrieval POST /api/memory/search // Search memories (progressive) GET /api/memory/:id // Get memory details // CBP POST /api/memory/cbp/query // Query collective best practices POST /api/memory/cbp/feedback // Submit CBP feedback ``` ### Clipboard Endpoints ```typescript theme={null} // List all entries GET /api/clipboard // Get entry by name or index POST /api/clipboard/get // Set named entry POST /api/clipboard // Push to stack POST /api/clipboard/push // Pop from stack DELETE /api/clipboard/pop // Delete entry DELETE /api/clipboard ``` See [Clipboard API Reference](/api/clipboard) for complete clipboard documentation. ## Next Steps Full details on the intelligent memory release Complete clipboard API documentation Clipboard methods in JavaScript Clipboard methods in Python