Skip to main content

​
Memory API

The Memory API provides long-term semantic memory for AI agents, enabling context persistence across sessions and significant token cost reduction.

​
Key Benefits

  • 90%+ Token Savings: Store and retrieve relevant context instead of resending full conversation history
  • Semantic Search: Find relevant memories based on meaning, not just keywords
  • Session Isolation: Keep memories organized by agent and session
  • GDPR Compliant: Full support for data deletion and export

​
Endpoints

​
Store Memory

Store a memory entry for an AI agent. 
POST /api/v1/memory/store
Request Body 
{
  "agent_id": "agent-123",
  "content": "User prefers dark mode and uses Python",
  "session_id": "session-456",
  "metadata": { "source": "user_preference" },
  "importance": 0.8
}
Response 
{
  "status": "stored",
  "entry_id": "mem_abc123",
  "agent_id": "agent-123"
}

​
Retrieve Memories

Retrieve relevant memories using semantic search. 
POST /api/v1/memory/retrieve
Request Body 
{
  "agent_id": "agent-123",
  "query": "What are the user's preferences?",
  "top_k": 5,
  "min_relevance": 0.5,
  "session_id": "session-456"
}
Response 
{
  "agent_id": "agent-123",
  "query": "What are the user's preferences?",
  "memories": [
    {
      "content": "User prefers dark mode and uses Python",
      "relevance": 0.92,
      "metadata": { "source": "user_preference" },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_searched": 15,
  "tokens_saved_estimate": 1250
}

​
Clear Memory

Clear memories for an agent or session. 
DELETE /api/v1/memory/{agent_id}?session_id={optional}
Response 
{
  "status": "cleared",
  "agent_id": "agent-123",
  "entries_deleted": 42
}

​
Get Stats

Get memory statistics for your project. 
GET /api/v1/memory/stats
Response 
{
  "total_entries": 1523,
  "total_agents": 45,
  "avg_entries_per_agent": 33.8,
  "estimated_tokens_saved": 125000,
  "storage_used_mb": 12.5
}

​
SDK Usage

from promptguard import PromptGuard

pg = PromptGuard(api_key="pg_xxx")

# Store memory
pg.memory.store(
    agent_id="my-agent",
    content="User prefers concise responses",
    importance=0.9
)

# Retrieve relevant memories
result = pg.memory.retrieve(
    agent_id="my-agent",
    query="How should I format my response?"
)

for memory in result["memories"]:
    print(f"Found: {memory['content']} (relevance: {memory['relevance']})")

​
Best Practices

  1. Use descriptive agent IDs: Make them meaningful for debugging
  2. Set appropriate importance scores: Higher importance = longer retention
  3. Clear sessions when done: Helps manage storage and privacy
  4. Combine with context injection: Use formattedContext directly in prompts