Mcp Memory Service

Name: Mcp Memory Service
Rating: 3.5 (1 reviews)
Author: radmanz

By radmanz 👁 25 views ▲ 0 votes

openclaw native access to mcp-memory-service through a plugin fixture

GitHub

Install

npm install
npm

Configuration Example

{
  "plugins": {
    "slots": {
      "memory": "openclaw-memory-mcp"
    },
    "entries": {
      "openclaw-memory-mcp": {
        "enabled": true,
        "config": {
          "base_url": "http://localhost:8200",
          "api_key": "${MCP_MEMORY_API_KEY}",
          "auto_inject": true,
          "auto_inject_limit": 15,
          "auto_inject_days": 7,
          "proactive_enabled": true,
          "post_flush_consolidation": true,
          "consolidation_horizon": "daily"
        }
      }
    }
  }
}

README

# OpenClaw MCP Memory Plugin

[![TypeScript](https://img.shields.io/badge/TypeScript-5.3%2B-blue)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A memory plugin for OpenClaw that integrates with [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service), providing:

- **Native agent partitioning** via `X-Agent-ID` header (no tag hacks)
- **Zero-effort context injection** via `before_agent_start` hook
- **Post-flush consolidation** for automatic knowledge graph building
- **Self-hosted infrastructure** (SQLite-vec + optional Cloudflare sync)
- **5ms read latency** with typed knowledge graph relationships

## Features

### Automatic Context Injection

Before each agent turn, the plugin automatically:
1. Loads the agent's identity
2. Recalls recent memories (last 7 days by default)
3. Fetches proactive context based on the current prompt
4. Injects formatted context into the agent's prompt

### 11 Memory Tools

| Tool | Description |
|------|-------------|
| `memory_store` | Store a new memory with type and tags |
| `memory_recall` | Semantic search across memories |
| `memory_search` | Search memories by similarity |
| `memory_fetch` | Get a specific memory by ID |
| `memory_connect` | Create typed relationships between memories |
| `memory_explore` | Explore the knowledge graph |
| `memory_save_context` | Save a context checkpoint |
| `memory_restore_context` | Restore a saved context |
| `memory_list_contexts` | List all saved contexts |
| `memory_flush_store` | Store session summary + trigger consolidation |
| `memory_reflect` | Analyze and reflect on memories |

### Knowledge Graph Relationships

The plugin supports typed edges between memories:

- `causes` - A causes B (asymmetric)
- `fixes` - A fixes B (asymmetric)
- `supports` - A supports B (asymmetric)
- `contradicts` - A contradicts B (symmetric)
- `follows` - A follows B (temporal)
- `related` - A related to B (generic)

## Installation

### Prerequisites

1. Deploy [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) (v10.18+)
2. Ensure OpenClaw gateway is installed

### Install Plugin

```bash
# Install from local path (copy)
openclaw plugins install /path/to/openclaw-memory-mcp

# Or symlink for active development
openclaw plugins install -l /path/to/openclaw-memory-mcp
```

### Build from Source

```bash
cd openclaw-memory-mcp
npm install
npm run build
```

## Configuration

Add to your OpenClaw configuration:

```json
{
  "plugins": {
    "slots": {
      "memory": "openclaw-memory-mcp"
    },
    "entries": {
      "openclaw-memory-mcp": {
        "enabled": true,
        "config": {
          "base_url": "http://localhost:8200",
          "api_key": "${MCP_MEMORY_API_KEY}",
          "auto_inject": true,
          "auto_inject_limit": 15,
          "auto_inject_days": 7,
          "proactive_enabled": true,
          "post_flush_consolidation": true,
          "consolidation_horizon": "daily"
        }
      }
    }
  }
}
```

### Configuration Options

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `base_url` | string | Yes | - | MCP memory service base URL |
| `api_key` | string | Yes | - | API key for authentication |
| `auto_inject` | boolean | No | `true` | Enable automatic context injection |
| `auto_inject_limit` | number | No | `15` | Max recent memories to inject |
| `auto_inject_days` | number | No | `7` | Days to look back for recent memories |
| `proactive_enabled` | boolean | No | `true` | Enable proactive context retrieval |
| `post_flush_consolidation` | boolean | No | `true` | Trigger consolidation after flush |
| `consolidation_horizon` | string | No | `"daily"` | Time horizon (`daily`, `weekly`, `monthly`) |

### Memory Flush Configuration

Add to your agent defaults:

```json
{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "prompt": "MANDATORY: Call memory_flush_store NOW with a comprehensive session summary...",
          "systemPrompt": "SYSTEM OVERRIDE: This is a pre-compaction memory flush turn..."
        }
      }
    }
  }
}
```

## Usage

### Enable the Plugin

```bash
# Enable the plugin
openclaw plugins enable openclaw-memory-mcp

# Restart the gateway
openclaw gateway restart

# Verify
openclaw plugins list
openclaw plugins doctor
```

### Tool Examples

#### Store a Memory

```typescript
// Agent calls:
memory_store({
  content: "SQLite is acceptable at 2 QPS for config storage",
  memory_type: "decision",
  tags: ["architecture", "database"]
})
```

#### Recall Memories

```typescript
// Agent calls:
memory_recall({
  query: "database decisions",
  limit: 10,
  time_range: "month"
})
```

#### Connect Memories

```typescript
// Agent calls:
memory_connect({
  from_memory_id: "mem-1",
  to_memory_id: "mem-2",
  relationship_type: "causes"
})
```

#### Session Flush

```typescript
// Agent calls during memory flush:
memory_flush_store({
  content: "Session summary: Implemented X, decided Y, learned Z...",
  tags: ["session-summary"]
})
```

## Development

### Scripts

```bash
npm run build        # Build TypeScript
npm run test         # Run tests
npm run test:watch   # Watch mode
npm run test:coverage # Run with coverage
npm run typecheck    # Type check only
npm run lint         # Run ESLint
```

### Project Structure

```
openclaw-memory-mcp/
├── openclaw.plugin.json    # Plugin manifest
├── index.ts                # Plugin entrypoint
├── index.test.ts           # Integration tests
├── src/
│   ├── client.ts           # MCP HTTP client
│   ├── client.test.ts
│   ├── hook.ts             # before_agent_start hook
│   ├── hook.test.ts
│   ├── tools/              # Tool implementations
│   │   ├── store.ts
│   │   ├── recall.ts
│   │   └── ...
│   ├── utils/              # Utilities
│   │   ├── agent-id.ts     # Session key parsing
│   │   └── formatter.ts    # Context formatting
│   └── types/              # TypeScript declarations
├── vitest.config.ts
├── tsconfig.json
└── package.json
```

### Test Coverage

- 119 tests passing
- 85%+ line coverage
- 80%+ branch coverage

## API Reference

### MCP-Memory-Service Endpoints Used

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/api/health` | Health check |
| POST | `/api/memories` | Store memory |
| POST | `/api/memories/search` | Semantic search |
| GET | `/api/memories/{id}` | Get by ID |
| DELETE | `/api/memories/{id}` | Delete memory |
| POST | `/api/memories/{id}/connect` | Create relationship |
| GET | `/api/memories/{id}/connected` | Get connected memories |
| POST | `/api/consolidation/trigger` | Trigger consolidation |
| POST | `/api/context/save` | Save context |
| GET | `/api/context/{id}` | Restore context |
| GET | `/api/context` | List contexts |

### Headers

All requests include:

```
X-Agent-ID: {agent_id}           # Required - partitions by agent
Content-Type: application/json   # Required for POST/PUT
Authorization: Bearer {api_key}  # Required if auth enabled
```

## Memory Types

| Type | Description |
|------|-------------|
| `observation` | General observations, facts |
| `decision` | Decisions, architecture choices |
| `learning` | Insights, lessons learned |
| `error` | Errors, failures |
| `pattern` | Patterns, trends |

## Migration from Penfield

See the [SPEC.md](./SPEC.md) for migration instructions from the Penfield memory plugin.

## Troubleshooting

### Plugin Not Loading

1. Check configuration: `openclaw plugins doctor`
2. Verify API key is set
3. Check mcp-memory-service is running: `curl http://localhost:8200/api/health`

### Context Not Injecting

1. Verify `auto_inject: true` in config
2. Check agent logs for hook execution
3. Ensure mcp-memory-service is accessible

### Memory Operations Failing

1. Check API key is valid
2. Verify base_url is correct
3. Check mcp-memory-service logs

## License

MIT

## References

- [mcp-memory-service GitHub](https://github.com/doobidoo/mcp-memory-service)
- [mcp-memory-service Wiki](https://github.com/doobidoo/mcp-memory-service/wiki)
- [OpenClaw Plugin Documentation](https://docs.openclaw.ai/advanced/plugins)
- [OpenClaw Hook System](https://docs.openclaw.ai/automation/hooks)

tools