{"id":30045363,"url":"https://github.com/jamesanz/memory-mcp","last_synced_at":"2025-08-22T20:05:55.001Z","repository":{"id":303906656,"uuid":"1017108665","full_name":"JamesANZ/memory-mcp","owner":"JamesANZ","description":"A simple MCP server that stores and retrieves memories from multiple LLMs","archived":false,"fork":false,"pushed_at":"2025-08-07T00:47:41.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-07T02:35:44.334Z","etag":null,"topics":["llm-memory","llms","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JamesANZ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-10T03:32:59.000Z","updated_at":"2025-08-07T00:47:41.000Z","dependencies_parsed_at":"2025-07-10T12:10:42.166Z","dependency_job_id":"9574f463-3342-4044-be72-9553df7d0f7d","html_url":"https://github.com/JamesANZ/memory-mcp","commit_stats":null,"previous_names":["jamesanz/memory-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JamesANZ/memory-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesANZ%2Fmemory-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesANZ%2Fmemory-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesANZ%2Fmemory-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesANZ%2Fmemory-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JamesANZ","download_url":"https://codeload.github.com/JamesANZ/memory-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JamesANZ%2Fmemory-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269220662,"owners_count":24380622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-07T02:00:09.698Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["llm-memory","llms","mcp-server"],"created_at":"2025-08-07T07:44:28.191Z","updated_at":"2025-08-22T20:05:54.979Z","avatar_url":"https://github.com/JamesANZ.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Memory MCP\n[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/JamesANZ/memory-mcp)](https://archestra.ai/mcp-catalog/jamesanz__memory-mcp)\n\nA Model Context Protocol (MCP) server for logging and retrieving memories from LLM conversations with intelligent context window caching capabilities.\n\n## Features\n\n- **Save Memories**: Store memories from LLM conversations with timestamps and LLM identification\n- **Retrieve Memories**: Get all stored memories with detailed metadata\n- **Add Memories**: Append new memories without overwriting existing ones\n- **Clear Memories**: Remove all stored memories\n- **Context Window Caching**: Archive, retrieve, and summarize conversation context\n- **Relevance Scoring**: Automatically score archived content relevance to current context\n- **Tag-based Search**: Categorize and search context by tags\n- **Conversation Orchestration**: External system to manage context window caching\n- **MongoDB Storage**: Persistent storage using MongoDB database\n\n## Installation\n\n1. Install dependencies:\n\n```bash\nnpm install\n```\n\n2. Build the project:\n\n```bash\nnpm run build\n```\n\n## Configuration\n\nSet the MongoDB connection string via environment variable:\n\n```bash\nexport MONGODB_URI=\"mongodb://localhost:27017\"\n```\n\nDefault: `mongodb://localhost:27017`\n\n## Usage\n\n### Running the MCP Server\n\nStart the MCP server:\n\n```bash\nnpm start\n```\n\n### Running the Conversation Orchestrator Demo\n\nTry the interactive CLI demo:\n\n```bash\nnpm run cli\n```\n\nThe CLI demo allows you to:\n\n- Add messages to simulate conversation\n- See automatic archiving when context gets full\n- Trigger manual archiving and retrieval\n- Create summaries of archived content\n- Monitor conversation status and get recommendations\n\n### Basic Memory Tools\n\n1. **save-memories**: Save all memories to the database, overwriting existing ones\n   - `memories`: Array of memory strings to save\n   - `llm`: Name of the LLM (e.g., 'chatgpt', 'claude')\n   - `userId`: Optional user identifier\n\n2. **get-memories**: Retrieve all memories from the database\n   - No parameters required\n\n3. **add-memories**: Add new memories to the database without overwriting existing ones\n   - `memories`: Array of memory strings to add\n   - `llm`: Name of the LLM (e.g., 'chatgpt', 'claude')\n   - `userId`: Optional user identifier\n\n4. **clear-memories**: Clear all memories from the database\n   - No parameters required\n\n### Context Window Caching Tools\n\n5. **archive-context**: Archive context messages for a conversation with tags and metadata\n   - `conversationId`: Unique identifier for the conversation\n   - `contextMessages`: Array of context messages to archive\n   - `tags`: Tags for categorizing the archived content\n   - `llm`: Name of the LLM (e.g., 'chatgpt', 'claude')\n   - `userId`: Optional user identifier\n\n6. **retrieve-context**: Retrieve relevant archived context for a conversation\n   - `conversationId`: Unique identifier for the conversation\n   - `tags`: Optional tags to filter by\n   - `minRelevanceScore`: Minimum relevance score (0-1, default: 0.1)\n   - `limit`: Maximum number of items to return (default: 10)\n\n7. **score-relevance**: Score the relevance of archived context against current conversation context\n   - `conversationId`: Unique identifier for the conversation\n   - `currentContext`: Current conversation context to compare against\n   - `llm`: Name of the LLM (e.g., 'chatgpt', 'claude')\n\n8. **create-summary**: Create a summary of context items and link them to the summary\n   - `conversationId`: Unique identifier for the conversation\n   - `contextItems`: Context items to summarize\n   - `summaryText`: Human-provided summary text\n   - `llm`: Name of the LLM (e.g., 'chatgpt', 'claude')\n   - `userId`: Optional user identifier\n\n9. **get-conversation-summaries**: Get all summaries for a specific conversation\n   - `conversationId`: Unique identifier for the conversation\n\n10. **search-context-by-tags**: Search archived context and summaries by tags\n    - `tags`: Tags to search for\n\n### Example Usage in LLM\n\n#### Basic Memory Operations\n\n1. **Save all memories** (overwrites existing):\n\n   ```\n   User: \"Save all my memories from this conversation to the MCP server\"\n   LLM: [Uses save-memories tool with current conversation memories]\n   ```\n\n2. **Retrieve all memories**:\n   ```\n   User: \"Get all my memories from the MCP server\"\n   LLM: [Uses get-memories tool to retrieve stored memories]\n   ```\n\n#### Context Window Caching Workflow\n\n1. **Archive context when window gets full**:\n\n   ```\n   User: \"The conversation is getting long, archive the early parts\"\n   LLM: [Uses archive-context tool to store old messages with tags]\n   ```\n\n2. **Score relevance of archived content**:\n\n   ```\n   User: \"How relevant is the archived content to our current discussion?\"\n   LLM: [Uses score-relevance tool to evaluate archived content]\n   ```\n\n3. **Retrieve relevant archived context**:\n\n   ```\n   User: \"Bring back the relevant archived information\"\n   LLM: [Uses retrieve-context tool to get relevant archived content]\n   ```\n\n4. **Create summaries for long conversations**:\n   ```\n   User: \"Summarize the early parts of our conversation\"\n   LLM: [Uses create-summary tool to condense archived content]\n   ```\n\n## Conversation Orchestration System\n\nThe `ConversationOrchestrator` class provides automatic context window management:\n\n### Key Features\n\n- **Automatic Archiving**: Archives content when context usage reaches 80%\n- **Intelligent Retrieval**: Retrieves relevant content when usage drops below 30%\n- **Relevance Scoring**: Uses keyword overlap to score archived content relevance\n- **Smart Tagging**: Automatically generates tags based on content keywords\n- **Conversation State Management**: Tracks active conversations and their context\n- **Recommendations**: Provides suggestions for optimal context management\n\n### Usage Example\n\n```typescript\nimport { ConversationOrchestrator } from \"./orchestrator.js\";\n\nconst orchestrator = new ConversationOrchestrator(8000); // 8k word limit\n\n// Add a message (triggers automatic archiving/retrieval)\nconst result = await orchestrator.addMessage(\n  \"conversation-123\",\n  \"This is a new message in the conversation\",\n  \"claude\",\n);\n\n// Check if archiving is needed\nif (result.archiveDecision?.shouldArchive) {\n  await orchestrator.executeArchive(result.archiveDecision, result.state);\n}\n\n// Check if retrieval is needed\nif (result.retrievalDecision?.shouldRetrieve) {\n  await orchestrator.executeRetrieval(result.retrievalDecision, result.state);\n}\n```\n\n## Database Schema\n\n### Basic Memory Structure\n\n```typescript\ntype BasicMemory = {\n  _id: ObjectId;\n  memories: string[]; // Array of memory strings\n  timestamp: Date; // When memories were saved\n  llm: string; // LLM identifier (e.g., 'chatgpt', 'claude')\n  userId?: string; // Optional user identifier\n};\n```\n\n### Extended Memory Structure (Context Caching)\n\n```typescript\ntype ExtendedMemory = {\n  _id: ObjectId;\n  memories: string[]; // Array of memory strings\n  timestamp: Date; // When memories were saved\n  llm: string; // LLM identifier\n  userId?: string; // Optional user identifier\n  conversationId?: string; // Unique conversation identifier\n  contextType?: \"active\" | \"archived\" | \"summary\";\n  relevanceScore?: number; // 0-1 relevance score\n  tags?: string[]; // Categorization tags\n  parentContextId?: ObjectId; // Reference to original content for summaries\n  messageIndex?: number; // Order within conversation\n  wordCount?: number; // Size tracking\n  summaryText?: string; // Condensed version\n};\n```\n\n## Context Window Caching Workflow\n\nThe orchestration system automatically:\n\n1. **Monitors conversation length** and context usage\n2. **Archives content** when context usage reaches 80%\n3. **Scores relevance** of archived content against current context\n4. **Retrieves relevant content** when usage drops below 30%\n5. **Creates summaries** to condense very long conversations\n\n### Key Features\n\n- **Conversation Grouping**: All archived content is linked to specific conversation IDs\n- **Relevance Scoring**: Simple keyword overlap scoring (can be enhanced with semantic similarity)\n- **Tag-based Organization**: Categorize content for easy retrieval\n- **Summary Linking**: Preserve links between summaries and original content\n- **Backward Compatibility**: All existing memory functions work unchanged\n- **Automatic Management**: No manual intervention required for basic operations\n\n## Development\n\nTo run in development mode:\n\n```bash\nnpm run build\nnode build/index.js\n```\n\nTo run the CLI demo:\n\n```bash\nnpm run cli\n```\n\n## License\n\nISC\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesanz%2Fmemory-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesanz%2Fmemory-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesanz%2Fmemory-mcp/lists"}