MCPInstall

agentmemory-persistent-memory

by reason-machinesAI & Agents

Add persistent memory to AI coding agents using agentmemory - remembers context, preferences, and decisions across sessions

Installs
216
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/ai-agent-skills --skill agentmemory-persistent-memory
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads agentmemory-persistent-memory automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

agentmemory-persistent-memory

Skill by ara.so — AI Agent Skills collection.

agentmemory provides persistent memory for AI coding agents (Claude Code, Cursor, Gemini CLI, Codex, etc.) so they remember architecture decisions, preferences, bugs, and context across sessions. Built on the iii engine, it achieves 95.2% retrieval accuracy (R@5) and reduces token usage by 92% compared to pasting full context.

What It Does

  • Cross-session memory: Agent remembers previous conversations, decisions, and code patterns
  • Zero setup: No external databases, runs locally
  • Works everywhere: MCP server + native plugins for Claude Code, Codex, OpenClaw, Hermes, Cursor, and more
  • Hybrid search: Combines embeddings + BM25 for accurate retrieval
  • Auto-capture: 12 hooks automatically store context from agent actions
  • Real-time viewer: Web UI to inspect and manage memories at http://localhost:3112

Installation

Global Installation (Recommended)

# Install globally to get the bare `agentmemory` command
npm install -g @agentmemory/agentmemory

# Start the memory server
agentmemory

# Server runs on http://localhost:3111 (API)
# Viewer runs on http://localhost:3112 (UI)

npx (No Install)

# Run without installing
npx @agentmemory/agentmemory

# Force latest version if cache is stale
npx -y @agentmemory/agentmemory@latest

Project-Level Installation

// package.json
{
  "dependencies": {
    "@agentmemory/agentmemory": "^0.9.16"
  }
}

// TypeScript/JavaScript usage
import { AgentMemory } from '@agentmemory/agentmemory';

const memory = new AgentMemory({
  port: 3111,
  dataDir: './data/memory'
});

await memory.start();

Quick Start

1. Start the Server

agentmemory

Output:

✓ agentmemory server running on http://localhost:3111
✓ Real-time viewer at http://localhost:3112
✓ MCP server ready for agent connections

2. Connect Your Agent

# Claude Code
agentmemory connect claude-code

# Codex CLI
agentmemory connect codex

# Cursor (via MCP)
agentmemory connect cursor

# Gemini CLI
agentmemory connect gemini-cli

# Generic MCP for any agent
agentmemory connect mcp

3. Demo Mode (Optional)

# Seed sample sessions and test recall
agentmemory demo

Agent-Specific Setup

Claude Code

Native plugin with 12 auto-hooks:

agentmemory connect claude-code

Creates ~/.claude-code/plugins/agentmemory.json:

{
  "name": "agentmemory",
  "memoryServer": "http://localhost:3111",
  "hooks": {
    "onStart": true,
    "onCommand": true,
    "onFileEdit": true,
    "onSearch": true,
    "onError": true,
    "onDecision": true
  }
}

Cursor (via MCP)

agentmemory connect cursor

Adds to ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/agentmemory", "mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/agentmemory", "mcp"]
    }
  }
}

Codex CLI

agentmemory connect codex

Creates ~/.codex/plugins/agentmemory.js:

module.exports = {
  name: 'agentmemory',
  memoryServer: 'http://localhost:3111',
  hooks: ['onStart', 'onCommand', 'onFileEdit', 'onSearch', 'onError', 'onDecision']
};

Core API Usage

TypeScript/JavaScript

import { AgentMemory } from '@agentmemory/agentmemory';

// Initialize
const memory = new AgentMemory({
  port: 3111,
  dataDir: './data/memory',
  embeddingModel: 'all-MiniLM-L6-v2', // Local, free
  enableViewer: true,
  viewerPort: 3112
});

await memory.start();

// Store a memory
await memory.store({
  sessionId: 'session-001',
  content: 'User prefers JWT auth with jose library for Edge compatibility',
  type: 'preference',
  tags: ['auth', 'jwt', 'edge'],
  confidence: 0.95
});

// Retrieve relevant memories
const results = await memory.search({
  query: 'authentication setup',
  sessionId: 'session-001',
  limit: 5
});

console.log(results);
// [
//   {
//     content: 'User prefers JWT auth with jose library...',
//     score: 0.92,
//     type: 'preference',
//     tags: ['auth', 'jwt', 'edge'],
//     timestamp: '2026-05-16T10:30:00Z'
//   }
// ]

// Store code context
await memory.storeCode({
  sessionId: 'session-001',
  filePath: 'src/middleware/auth.ts',
  language: 'typescript',
  summary: 'JWT middleware using jose, validates tokens on Edge runtime',
  keyDecisions: [
    'Chose jose over jsonwebtoken for Edge compatibility',
    'Token expiry set to 7 days',
    'Refresh tokens stored in httpOnly cookies'
  ]
});

// Recall at session start
const context = await memory.recallForSession('session-002');
console.log(context.relevantMemories);
// Agent automatically gets context from previous sessions

REST API

# Store memory
curl -X POST http://localhost:3111/api/memory/store \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-001",
    "content": "User prefers TypeScript strict mode",
    "type": "preference",
    "tags": ["typescript", "config"],
    "confidence": 0.9
  }'

# Search memories
curl -X POST http://localhost:3111/api/memory/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript configuration",
    "sessionId": "session-001",
    "limit": 5
  }'

# Get session context
curl http://localhost:3111/api/memory/session/session-001

# Delete memory
curl -X DELETE http://localhost:3111/api/memory/delete/mem_abc123xyz

# Health check
curl http://localhost:3111/health

MCP Server (Model Context Protocol)

agentmemory exposes 51 MCP tools for agent integration:

Available Tools

// Memory operations
- memory_store: Store new memory
- memory_search: Search memories by query
- memory_recall: Get context for session
- memory_update: Update existing memory
- memory_delete: Delete specific memory
- memory_list: List all memories (paginated)

// Session management
- session_create: Start new session
- session_get: Get session details
- session_list: List all sessions
- session_archive: Archive completed session

// Code context
- code_store: Store code snippet with context
- code_search: Search code memories
- code_link: Link memories to code files

// Preferences
- preference_set: Store user preference
- preference_get: Retrieve preference
- preference_list: List all preferences

// Knowledge graph
- graph_add_node: Add knowledge node
- graph_add_edge: Connect nodes
- graph_query: Query relationships
- graph_traverse: Walk knowledge graph

// Analytics
- stats_get: Get memory statistics
- stats_session: Session-level stats
- stats_recall_accuracy: Retrieval metrics

MCP Client Example

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@agentmemory/agentmemory', 'mcp']
});

const client = new Client({
  name: 'my-agent',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

// Call MCP tool
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'memory_store',
    arguments: {
      sessionId: 'session-001',
      content: 'User wants error handling with Zod validation',
      type: 'decision',
      tags: ['error-handling', 'validation', 'zod']
    }
  }
});

console.log(result);

Configuration

Environment Variables

# Server settings
AGENTMEMORY_PORT=3111
AGENTMEMORY_VIEWER_PORT=3112
AGENTMEMORY_DATA_DIR=./data/memory

# Embedding model (local)
AGENTMEMORY_EMBEDDING_MODEL=all-MiniLM-L6-v2

# Or use OpenAI embeddings (requires API key)
OPENAI_API_KEY=your_openai_key_here
AGENTMEMORY_EMBEDDING_PROVIDER=openai
AGENTMEMORY_EMBEDDING_MODEL=text-embedding-3-small

# Search tuning
AGENTMEMORY_HYBRID_ALPHA=0.7  # 0.7 = 70% embeddings, 30% BM25
AGENTMEMORY_MAX_RESULTS=10

# Memory lifecycle
AGENTMEMORY_AUTO_ARCHIVE_DAYS=30
AGENTMEMORY_MIN_CONFIDENCE=0.5

# Hooks (for Claude Code, Codex)
AGENTMEMORY_ENABLE_HOOKS=true
AGENTMEMORY_HOOK_ON_FILE_EDIT=true
AGENTMEMORY_HOOK_ON_COMMAND=true
AGENTMEMORY_HOOK_ON_ERROR=true

Configuration File

Create agentmemory.config.json:

{
  "server": {
    "port": 3111,
    "viewerPort": 3112,
    "dataDir": "./data/memory"
  },
  "embedding": {
    "provider": "local",
    "model": "all-MiniLM-L6-v2"
  },
  "search": {
    "hybridAlpha": 0.7,
    "maxResults": 10,
    "minConfidence": 0.5
  },
  "lifecycle": {
    "autoArchiveDays": 30,
    "pruneInactive": true
  },
  "hooks": {
    "onStart": true,
    "onCommand": true,
    "onFileEdit": true,
    "onSearch": true,
    "onError": true,
    "onDecision": true
  }
}

Load config:

agentmemory --config ./agentmemory.config.json

Common Patterns

Pattern 1: Architecture Decision Capture

// When agent makes architectural decision, store it
await memory.store({
  sessionId: currentSession,
  content: 'Decided to use PostgreSQL with Prisma ORM for type safety',
  type: 'decision',
  tags: ['architecture', 'database', 'prisma', 'postgresql'],
  confidence: 0.95,
  metadata: {
    rationale: 'Team familiar with Prisma, need strong typing',
    alternatives: ['MySQL + Drizzle', 'MongoDB'],
    impact: 'high',
    reversible: false
  }
});

// Next session, agent recalls this automatically
const context = await memory.recallForSession(newSession);
// Agent knows: "Previously decided on PostgreSQL + Prisma for type safety"

Pattern 2: Code Pattern Memory

// Store reusable code pattern
await memory.storeCode({
  sessionId: currentSession,
  filePath: 'src/lib/api-client.ts',
  language: 'typescript',
  summary: 'API client with retry logic and exponential backoff',
  pattern: `
    export async function fetchWithRetry(url: string, options?: RequestInit) {
      let attempt = 0;
      while (attempt < 3) {
        try {
          return await fetch(url, options);
        } catch (err) {
          if (attempt === 2) throw err;
          await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
          attempt++;
        }
      }
    }
  `,
  tags: ['api', 'retry', 'fetch', 'resilience'],
  keyDecisions: [
    '3 retries with exponential backoff',
    'Throws on final failure',
    'No retry on 4xx errors (only network failures)'
  ]
});

// Later, when user asks about API calls
const codeMemories = await memory.search({
  query: 'api error handling',
  type: 'code',
  limit: 3
});
// Agent suggests: "We use fetchWithRetry from api-client.ts for resilience"

Pattern 3: Bug Fix Memory

// When bug is found and fixed
await memory.store({
  sessionId: currentSession,
  content: 'Fixed race condition in WebSocket reconnection logic',
  type: 'bug_fix',
  tags: ['websocket', 'race-condition', 'concurrency'],
  confidence: 1.0,
  metadata: {
    symptom: 'Duplicate connections causing message echoes',
    rootCause: 'reconnect() called before disconnect() completed',
    fix: 'Added connectionLock mutex to serialize connect/disconnect',
    filePath: 'src/websocket/connection.ts',
    linesChanged: '45-67',
    testAdded: 'tests/websocket/reconnect.test.ts'
  }
});

// Prevents re-introducing similar bugs
const pastBugs = await memory.search({
  query: 'websocket connection issues',
  type: 'bug_fix'
});
// Agent warns: "Watch out - we had a race condition here before (see connectionLock)"

Pattern 4: Preference Learning

// Capture user preferences over time
await memory.store({
  sessionId: currentSession,
  content: 'User prefers named exports over default exports',
  type: 'preference',
  tags: ['code-style', 'exports', 'modules'],
  confidence: 0.85
});

await memory.store({
  sessionId: currentSession,
  content: 'User wants all async errors wrapped in Result<T, E> type',
  type: 'preference',
  tags: ['error-handling', 'types', 'functional'],
  confidence: 0.9
});

// Agent adapts to preferences automatically
const prefs = await memory.search({
  query: 'code style preferences',
  type: 'preference'
});
// Agent generates code matching user's style without being told

Pattern 5: Cross-File Context

// Link related code across files
await memory.storeCode({
  sessionId: currentSession,
  filePath: 'src/middleware/auth.ts',
  language: 'typescript',
  summary: 'JWT authentication middleware',
  tags: ['auth', 'jwt', 'middleware']
});

await memory.linkCode({
  from: 'src/middleware/auth.ts',
  to: 'src/routes/api.ts',
  relationship: 'used_by',
  context: 'All /api/* routes use JWT auth middleware'
});

await memory.linkCode({
  from: 'src/middleware/auth.ts',
  to: 'tests/middleware/auth.test.ts',
  relationship: 'tested_by',
  context: 'Test coverage: token validation, expiry, refresh'
});

// Agent understands impact of changes
const linkedFiles = await memory.getCodeLinks('src/middleware/auth.ts');
// Agent warns: "Changing auth.ts affects 12 API routes and has test coverage"

Real-Time Viewer

Open http://localhost:3112 to see:

  • Memory timeline: Visual history of all stored memories
  • Session explorer: Browse by session, see context evolution
  • Search interface: Test queries, see retrieval scores
  • Knowledge graph: Visual map of connected memories
  • Stats dashboard: Recall accuracy, token savings, storage usage

Viewer API

// Programmatic access to viewer data
const viewerData = await fetch('http://localhost:3112/api/viewer/data').then(r => r.json());

console.log(viewerData);
// {
//   sessions: [...],
//   memories: [...],
//   stats: { totalMemories: 1247, avgRecall: 0.952, tokensSaved: 168420 }
// }

CLI Commands

# Start server
agentmemory

# Start with custom port
agentmemory --port 4000 --viewer-port 4001

# Start in background
agentmemory --daemon

# Stop daemon
agentmemory stop

# Connect agent
agentmemory connect <agent-name>

# Run demo
agentmemory demo

# Export memories
agentmemory export --format json --output memories.json

# Import memories
agentmemory import --input memories.json

# Clear all memories (with confirmation)
agentmemory clear

# Show stats
agentmemory stats

# Health check
agentmemory health

# Update to latest
agentmemory update

Troubleshooting

Server Won't Start

# Check if port is in use
lsof -i :3111

# Kill existing process
kill -9 $(lsof -t -i:3111)

# Start on different port
agentmemory --port 4000

Agent Not Connecting

# Verify server is running
curl http://localhost:3111/health

# Check MCP configuration
cat ~/Library/Application\ Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

# Test MCP connection manually
npx @agentmemory/agentmemory mcp

Poor Recall Accuracy

// Increase hybrid search weight toward embeddings
AGENTMEMORY_HYBRID_ALPHA=0.85  // 85% embeddings, 15% BM25

// Or switch to OpenAI embeddings for better quality
OPENAI_API_KEY=your_key_here
AGENTMEMORY_EMBEDDING_PROVIDER=openai
AGENTMEMORY_EMBEDDING_MODEL=text-embedding-3-large

Memory Storage Growing Large

# Archive old sessions
agentmemory archive --older-than 30d

# Prune low-confidence memories
agentmemory prune --min-confidence 0.5

# Compact database
agentmemory compact

Viewer Not Loading

# Check viewer port
curl http://localhost:3112

# Restart with viewer explicitly enabled
agentmemory --enable-viewer --viewer-port 3112

npx Cache Issues

# Clear npx cache (macOS/Linux)
rm -rf ~/.npm/_npx

# Windows
# Delete %LOCALAPPDATA%\npm-cache\_npx

# Force latest version
npx -y @agentmemory/agentmemory@latest

Advanced: iii Engine Integration

agentmemory is built on the iii engine, a knowledge processing system. You can use iii directly for custom memory backends:

import { IIIEngine } from '@iii-hq/iii';

const engine = new IIIEngine({
  storage: 'local',
  embeddings: 'all-MiniLM-L6-v2'
});

// Store knowledge node
await engine.store({
  content: 'User prefers Tailwind CSS for styling',
  type: 'preference',
  tags: ['ui', 'css', 'tailwind'],
  confidence: 0.9
});

// Query with iii's advanced graph traversal
const results = await engine.query({
  semantic: 'css framework choice',
  graphDepth: 2,
  includeRelated: true
});

Environment Setup Example

# .env file for production
AGENTMEMORY_PORT=3111
AGENTMEMORY_VIEWER_PORT=3112
AGENTMEMORY_DATA_DIR=/var/lib/agentmemory
AGENTMEMORY_EMBEDDING_PROVIDER=local
AGENTMEMORY_EMBEDDING_MODEL=all-MiniLM-L6-v2
AGENTMEMORY_HYBRID_ALPHA=0.75
AGENTMEMORY_AUTO_ARCHIVE_DAYS=90
AGENTMEMORY_MIN_CONFIDENCE=0.6
AGENTMEMORY_ENABLE_HOOKS=true
AGENTMEMORY_LOG_LEVEL=info

Performance Notes

  • Embedding: Local model (all-MiniLM-L6-v2) processes ~500 tokens/sec on M1 Mac
  • Search: Hybrid search returns results in <50ms for 10K memories
  • Storage: ~1KB per memory average, ~10MB for 10K memories
  • Startup: Cold start ~2 seconds, warm start <500ms
  • Token savings: 92% reduction vs. full context pasting (see benchmarks)

Resources

FAQ

What does the agentmemory-persistent-memory skill do?

Add persistent memory to AI coding agents using agentmemory - remembers context, preferences, and decisions across sessions

How do I install agentmemory-persistent-memory?

Run npx skills add https://github.com/reason-machines/ai-agent-skills --skill agentmemory-persistent-memory in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/agentmemory-persistent-memory/ (personal) or .claude/skills/agentmemory-persistent-memory/ (project).

Which AI agents can use agentmemory-persistent-memory?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is agentmemory-persistent-memory safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains agentmemory-persistent-memory?

It is published by reason-machines in reason-machines/ai-agent-skills. It has 216 recorded installs.

More from reason-machines/ai-agent-skills

View all →

agency-agents-zh-skill

reason-machines/ai-agent-skills

Open the skill to read its SKILL.md instructions.

AI & Agents322 installs

agent-reach-internet-access

reason-machines/ai-agent-skills

Open the skill to read its SKILL.md instructions.

AI & Agents228 installs

agent-sprite-forge-2d-game-assets

reason-machines/ai-agent-skills

Open the skill to read its SKILL.md instructions.

Media & Creative216 installs

awesome-agent-skills

reason-machines/ai-agent-skills

Open the skill to read its SKILL.md instructions.

AI & Agents214 installs

oh-my-openagent-orchestration

reason-machines/ai-agent-skills

Open the skill to read its SKILL.md instructions.

AI & Agents211 installs

tencentdb-agent-memory

reason-machines/ai-agent-skills

Open the skill to read its SKILL.md instructions.

AI & Agents203 installs

Popular ai & agents skills

View category →

google-agents-cli-publish

google/agents-cli

This skill should be used when the user wants to "publish an agent", "publish my ADK agent", "register an agent with Gemini", "publish to Gemini" (formerly Gemini Enterprise), or needs guidance on the agents-cli publish gemini command. Also use when the user wants to "manage agents in Agent Registry", "list/update/delete registered agents", or "register an MCP server". Covers ADK vs A2A registration modes, programmatic and interactive usage, flag reference, auto-detection from deployment metadata, Agent Registry fleet management, and troubleshooting. Part of the agents-cli skills suite. Do NOT use for deployment (use google-agents-cli-deploy).

AI & Agents513.9K installs

google-agents-cli-eval

google/agents-cli

This skill should be used when the user wants to "run an evaluation", "evaluate my agent", "evaluate my ADK agent", "write an eval dataset", "analyze eval failures", "compare eval results", "optimize agent", or needs guidance on the Gemini platform eval methodology and the Quality Flywheel. Covers eval metrics, dataset schema, LLM-as-judge scoring, and common failure causes. Applies to any agents-cli project, whatever framework the agent is written in. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), deployment (use google-agents-cli-deploy), or project scaffolding (use google-agents-cli-scaffold).

AI & Agents513.5K installs

skill-creator

anthropics/skills

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

OfficialAI & Agents416.4K installs

codex-pet

prime-skills/runcomfy-agent-skills

Codex Pet generator on RunComfy. Build a Codex-compatible Codex Pet spritesheet.webp + pet.json from a single reference image, drop it into ${CODEXHOME:-$HOME/.codex}/pets/ / and Codex picks it up as a custom Codex Pet next to the 8 built-ins. This skill produces the exact Codex Pet atlas Codex expects (1536x1872 PNG/WebP, 8 cols x 9 rows, 192x208 cells, 9 animation states — idle, running-right, running-left, waving, jumping, failed, waiting, running, review). Calls OpenAI GPT Image 2 edit ONCE via the local RunComfy CLI as runcomfy run openai/gpt-image-2/edit to produce a canonical Codex Pet pose, then assembles all 9 animation rows programmatically with ImageMagick micro-transforms — no Codex Pro, no $imagegen, no OPENAIAPIKEY required, only RUNCOMFYTOKEN. Triggers on "codex pet", "create codex pet", "make codex pet", "hatch codex pet", "/hatch image", "desktop pet codex", "codex pets", "spritesheet.webp", or any explicit ask to build a custom pet for OpenAI Codex.

AI & Agents402.1K installs

full-output-enforcement

leonxlnx/taste-skill

Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.

AI & Agents401K installs

executing-plans

obra/superpowers

Use when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available

AI & Agents245.7K installs