# MCP Session Memory Bridge

A Model Context Protocol (MCP) server that provides cross-session memory capabilities for AI agents. This solves the common problem of "session amnesia" where agents lose context between sessions.

## Features

- **24-Hour Event Stream**: Maintains a rolling `RECENT_EVENTS.md` file with events from the last 24 hours
- **Daily Memory Archives**: Automatically creates daily memory files for long-term storage
- **Session Context Preservation**: Loads relevant context when starting a new session
- **Event Tagging**: Tag events with categories like [Decision], [Action], [Context], [User]
- **Searchable History**: Full-text search across all memory files

## Installation

```bash
npm install mcp-session-memory
```

## Usage

### Start the MCP Server

```bash
npx mcp-session-memory --workspace /path/to/workspace
```

### In Your Agent Code

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

const transport = new StdioClientTransport({
  command: "npx",
  args: ["mcp-session-memory", "--workspace", "./workspace"]
});

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

await client.connect(transport);

// Record an event
await client.callTool("memory_record", {
  category: "Decision",
  content: "Approved new skill generation workflow",
  tags: ["workflow", "approval"]
});

// Query memory
const results = await client.callTool("memory_query", {
  query: "skill workflow decisions",
  limit: 5
});

// Get session context
const context = await client.callTool("session_getContext", {
  maxAge: "24h"
});
```

## Tools

### memory_record
Records a new event to the memory stream.

**Input:**
- `category`: "Decision" | "Action" | "Context" | "User" | "System"
- `content`: string - The event content
- `tags`: string[] - Optional tags for categorization
- `importance`: number (1-10) - Importance level

### memory_query
Searches across all memory files.

**Input:**
- `query`: string - Search query
- `limit`: number - Maximum results (default: 10)
- `categories`: string[] - Filter by categories

### session_getContext
Gets relevant context for starting a new session.

**Input:**
- `maxAge`: string - e.g., "24h", "7d" (default: "24h")
- `limit`: number - Maximum events to return

### memory_getRecent
Gets recent events from the stream.

**Input:**
- `hours`: number - Hours to look back (default: 24)
- `limit`: number - Maximum events to return

## File Structure

```
workspace/
├── RECENT_EVENTS.md      # 24-hour rolling event stream
├── memories/
│   ├── 2026-03-15.md    # Today's memory
│   ├── 2026-03-14.md
│   └── ...
└── .memory-config.json   # Configuration
```

## RECENT_EVENTS.md Format

```markdown
# Recent Events - Last 24 Hours

## 2026-03-15 10:30:00
- [Decision] Approved new skill generation workflow
- [Tags] workflow, approval

## 2026-03-15 09:15:00
- [Action] Completed morning operation for EvoMap
- [Context] Active project: Community Platform
```

## Configuration

```json
{
  "workspace": "./workspace",
  "retentionDays": 30,
  "maxEventsPerFile": 100,
  "categories": ["Decision", "Action", "Context", "User", "System"]
}
```

## License

MIT