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

Concentric Rings

Five memory ring types inspired by how humans form and retain knowledge

Collective Best Practices

Privacy-preserving community wisdom with k-anonymity

Intelligent Forgetting

Token-based decay engine that compresses memories over time

Z-Reports

End-of-session summaries that capture key observations and decisions

Progressive Retrieval

3-layer retrieval system optimized for token efficiency

Persistent Clipboard

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:

Fresh Memory
Procedures
Practice/Habits
Long-term
Shocks

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”

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:

Layer 1: Search

Returns content_essence or content_summary for each match (50-150 tokens per result). Ideal for scanning many memories quickly.

Layer 2: Timeline

Adds temporal context — when the memory was created, which session, and related observations. Useful for understanding sequence of events.

Layer 3: Full Details

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

HMAC-SHA256 Hashing

Patterns are normalized and hashed before storage. The original pattern text is never stored in the collective pool.

k-Anonymity (k>=3)

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

Named Access
Indexed Access

How it works: Store data with semantic keys for direct retrieval.Example Keys: user_preferences, last_search_results, conversation_contextBest for:

Configuration and preferences
Caching frequently used data
Sharing state between tools
Key-based lookups

// 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 dataBest for:

LIFO (Last-In-First-Out) workflows
Undo/redo operations
Processing pipelines
Temporary data storage

// 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

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

Text Content
Binary Content

For plain text and JSON data:

{
  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:

{
  value: "iVBORw0KGgoAAAANSUhEUgAA...",  // base64 encoded
  contentType: "image/png",
  encoding: "base64"
}

Supported encodings: base64, hex

Usage Examples

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);

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)

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

// 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

Entry Size

Maximum 2 MB per entry value

Default TTL

24 hours if not specified

Rate Limits

Standard API rate limits apply

Profile Scope

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

Access Memory Page

Navigate to Memory in the sidebar to view your memories and clipboard entries

Start a Session (via MCP)

Use pluggedin_memory_session_start to begin tracking observations in your AI session

Record Observations

Use pluggedin_memory_observe during your session to capture important patterns and decisions

End Session

Use pluggedin_memory_session_end to generate a Z-report summarizing the session

Search Memories

Use pluggedin_memory_search to find relevant past memories using natural language queries

API Reference

Memory Endpoints

// 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

// 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 for complete clipboard documentation.

Next Steps

v3.1.0 Release Notes

Full details on the intelligent memory release

API Reference

Complete clipboard API documentation

JavaScript SDK

Clipboard methods in JavaScript

Python SDK

Clipboard methods in Python

​Memory & Intelligent Knowledge

​Overview

Concentric Rings

Collective Best Practices

Intelligent Forgetting

Z-Reports

Progressive Retrieval

Persistent Clipboard

​Intelligent Memory System

​Concentric Memory Rings

​Intelligent Forgetting (Decay Engine)

​Progressive Retrieval (3-Layer)

​Z-Reports (Session Summaries)

​Vector Search Infrastructure

​Collective Best Practices (CBP)

​How It Works

​Privacy Guarantees

HMAC-SHA256 Hashing

k-Anonymity (k>=3)

​Feedback Loop

​Memory MCP Tools

​Session & Observation Tools

​Collective Best Practices Tools

​Persistent Clipboard

​Access Patterns

​Clipboard MCP Tools

​Named Operations

​Stack Operations

​Data Structure

​Source Types

​Content Types & Encoding

​Usage Examples

​Sharing Data Between Tools

​Processing Pipeline with Stack

​Limits & Quotas

Entry Size

Default TTL

Rate Limits

Profile Scope

​Security & Isolation

​Access Control

​Data Protection

​Quick Start

​API Reference

​Memory Endpoints

​Clipboard Endpoints

​Next Steps

v3.1.0 Release Notes

API Reference

JavaScript SDK

Python SDK

Memory & Intelligent Knowledge

Overview

Intelligent Memory System

Concentric Memory Rings

Intelligent Forgetting (Decay Engine)

Progressive Retrieval (3-Layer)

Z-Reports (Session Summaries)

Vector Search Infrastructure

Collective Best Practices (CBP)

How It Works

Privacy Guarantees

Feedback Loop

Memory MCP Tools

Session & Observation Tools

Collective Best Practices Tools

Persistent Clipboard

Access Patterns

Clipboard MCP Tools

Named Operations

Stack Operations

Data Structure

Source Types

Content Types & Encoding

Usage Examples

Sharing Data Between Tools

Processing Pipeline with Stack

Limits & Quotas

Security & Isolation

Access Control

Data Protection

Quick Start

API Reference

Memory Endpoints

Clipboard Endpoints

Next Steps