{"id":30805563,"url":"https://github.com/aaronsb/memory-graph","last_synced_at":"2025-09-06T00:59:09.524Z","repository":{"id":275714271,"uuid":"926956373","full_name":"aaronsb/memory-graph","owner":"aaronsb","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-22T14:09:30.000Z","size":297,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-22T15:39:18.936Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-02-04T06:35:16.000Z","updated_at":"2025-05-17T23:19:33.000Z","dependencies_parsed_at":"2025-02-25T18:25:56.277Z","dependency_job_id":"1d72e5b2-628b-4a4b-9c6d-57539169cefa","html_url":"https://github.com/aaronsb/memory-graph","commit_stats":null,"previous_names":["aaronsb/memory-graph"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/memory-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/memory-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273842816,"owners_count":25177921,"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-09-05T02:00:09.113Z","response_time":402,"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":[],"created_at":"2025-09-06T00:59:07.325Z","updated_at":"2025-09-06T00:59:09.513Z","avatar_url":"https://github.com/aaronsb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Memory Graph MCP Server\n\nAn MCP server that provides persistent memory capabilities through a local knowledge graph implementation. This server enables AI assistants to maintain context and information across chat sessions using a graph-based storage system.\n\n## Features\n\n- Domain-based memory organization for context isolation\n- Store and retrieve memories with content, tags, and metadata\n- Cross-domain memory references with relationship tracking\n- Memory domain transfer capability\n- Multiple storage backends (JSON, SQLite, and MariaDB)\n- Multiple transport protocols (STDIO and HTTP)\n- Full-text search capabilities with SQL-based storage backends\n- Advanced content search with fuzzy matching and regex support\n- Combine multiple search strategies (content, path, tags)\n- Flexible result sorting and relevance scoring\n- Graph traversal across domains and relationships\n- Mermaid graph visualization for memory connections\n- Docker and Docker Compose support\n\n## Documentation\n\n### Getting Started\n- [Getting Started Guide](docs/guides/getting-started.md) - Quick setup and basic usage guide\n- [Use Cases](docs/guides/use-cases.md) - Examples of how to use Memory Graph in real-world scenarios\n- [Configuration](docs/guides/configuration.md) - Comprehensive configuration options\n\n### Features\n- [Storage Overview](docs/features/storage/overview.md) - Overview of storage backends\n- [Transport Overview](docs/features/transport/overview.md) - Overview of transport types\n\n### Core Concepts\n- [Memory Architecture](docs/concepts/memory-architecture.md) - Domain-based memory system\n- [Graph Model](docs/concepts/graph-model.md) - Graph data model explanation\n\n### Reference\n- [Memory Tools Reference](docs/reference/memory-tools-reference.md) - Comprehensive tool documentation\n- [Database Schemas](docs/reference/database-schemas.md) - Technical reference for database schemas\n\n### Developer Documentation\n- [Architecture](docs/development/architecture.md) - System architecture and design patterns\n- [Contributing](docs/development/contributing.md) - Contributing guidelines\n- [Testing](docs/development/testing.md) - Testing strategy\n\n## Installation\n\n### Local Installation\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the TypeScript code\nnpm run build\n\n# Clean build directory\nnpm run clean\n```\n\n### Docker Installation\n\nThe server is available as a Docker container from GitHub Container Registry:\n\n```bash\n# Pull the image\ndocker pull ghcr.io/aaronsb/memory-graph:latest\n\n# Or build locally\n./scripts/build-local.sh\n```\n\n## Usage\n\n### Docker Usage\n\nRun the container with your desired configuration:\n\n```bash\n# Using STDIO transport (default)\ndocker run -v /path/to/data:/app/data \\\n  -e MEMORY_DIR=/app/data \\\n  -e TRANSPORT_TYPE=STDIO \\\n  -e STORAGE_TYPE=sqlite \\\n  ghcr.io/aaronsb/memory-graph:latest\n\n# Using HTTP transport\ndocker run -v /path/to/data:/app/data \\\n  -e MEMORY_DIR=/app/data \\\n  -e TRANSPORT_TYPE=HTTP \\\n  -e PORT=3000 \\\n  -e HOST=127.0.0.1 \\\n  -p 3000:3000 \\\n  ghcr.io/aaronsb/memory-graph:latest\n\n# Using MariaDB storage\ndocker run -v /path/to/data:/app/data \\\n  --network=host \\\n  -e MEMORY_DIR=/app/data \\\n  -e STORAGE_TYPE=mariadb \\\n  -e MARIADB_HOST=localhost \\\n  -e MARIADB_PORT=3306 \\\n  -e MARIADB_USER=memory_user \\\n  -e MARIADB_PASSWORD=secure_password \\\n  -e MARIADB_DATABASE=memory_graph \\\n  ghcr.io/aaronsb/memory-graph:latest\n```\n\n### Docker Compose\n\nFor convenience, a Docker Compose configuration is provided:\n\n```bash\n# Start with Docker Compose\ndocker-compose up -d\n\n# Stop services\ndocker-compose down\n```\n\n### Local Usage\n\n```bash\n# Start the server\nnpm start\n\n# Run using custom configuration\nMEMORY_DIR=/path/to/data STORAGE_TYPE=sqlite npm start\n```\n\n## Configuration\n\nThe server can be configured using environment variables:\n\n### General Configuration\n\n- `MEMORY_DIR`: Directory to store memory files (default: `./data`)\n- `MEMORY_FILES`: Comma-separated list of specific memory files to use\n- `LOAD_ALL_FILES`: Set to 'true' to load all JSON files in the storage directory\n- `DEFAULT_PATH`: Default path for storing memories\n- `STRICT_MODE`: Set to 'true' to ensure all logging goes to stderr, preventing interference with JSON-RPC communication on stdout\n\n### Storage Configuration\n\n- `STORAGE_TYPE`: Storage backend to use (`json`, `sqlite`, or `mariadb`, default: `json`)\n\n#### MariaDB Configuration (when using `STORAGE_TYPE=mariadb`)\n\n- `MARIADB_HOST`: Database server hostname (default: `localhost`)\n- `MARIADB_PORT`: Database server port (default: `3306`)\n- `MARIADB_USER`: Database username (default: `root`)\n- `MARIADB_PASSWORD`: Database password (default: empty)\n- `MARIADB_DATABASE`: Database name (default: `memory_graph`)\n- `MARIADB_CONNECTION_LIMIT`: Maximum number of connections in the pool (default: `10`)\n\n### Transport Configuration\n\n- `TRANSPORT_TYPE`: Communication transport to use (`STDIO` or `HTTP`, default: `STDIO`)\n- `PORT`: Port number for HTTP transport (required when `TRANSPORT_TYPE=HTTP`)\n- `HOST`: Host address for HTTP transport (default: `127.0.0.1`, only used when `TRANSPORT_TYPE=HTTP`)\n\n## MCP Configuration\n\nTo use this server with an AI assistant via MCP, add it to your MCP configuration file:\n\n### STDIO Transport (Default)\n\n```json\n{\n  \"mcpServers\": {\n    \"memory-graph\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/memory-graph/build/index.js\"],\n      \"env\": {\n        \"MEMORY_DIR\": \"/path/to/memory/storage\",\n        \"STORAGE_TYPE\": \"sqlite\",\n        \"STRICT_MODE\": \"true\"\n      },\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n### HTTP Transport\n\n```json\n{\n  \"mcpServers\": {\n    \"memory-graph\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/memory-graph/build/index.js\"],\n      \"env\": {\n        \"MEMORY_DIR\": \"/path/to/memory/storage\",\n        \"STORAGE_TYPE\": \"sqlite\",\n        \"TRANSPORT_TYPE\": \"HTTP\",\n        \"PORT\": \"3000\",\n        \"STRICT_MODE\": \"true\"\n      },\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n### Docker with MariaDB\n\n```json\n{\n  \"mcpServers\": {\n    \"memory-graph\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"--rm\",\n        \"-i\",\n        \"--network=host\",\n        \"-v\", \"/path/to/data:/app/data\",\n        \"-e\", \"MEMORY_DIR=/app/data\",\n        \"-e\", \"STORAGE_TYPE=mariadb\",\n        \"-e\", \"MARIADB_HOST=localhost\",\n        \"-e\", \"MARIADB_PORT=3306\",\n        \"-e\", \"MARIADB_USER=memory_user\",\n        \"-e\", \"MARIADB_PASSWORD=secure_password\",\n        \"-e\", \"MARIADB_DATABASE=memory_graph\",\n        \"-e\", \"STRICT_MODE=true\",\n        \"ghcr.io/aaronsb/memory-graph:latest\"\n      ],\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n## Storage Options\n\nThe Memory Graph MCP supports three storage backends:\n\n- **JSON**: Simple file-based storage (default)\n  - One JSON file per domain in the `memories/` directory\n  - Good for smaller datasets and simple deployments\n  - Easy to inspect and manually edit if needed\n\n- **SQLite**: Database storage with improved performance\n  - Single SQLite database file for all domains\n  - Better performance for large datasets\n  - Full-text search capabilities\n  - More efficient memory usage\n  - Good for local deployments\n\n- **MariaDB**: Production-ready database storage\n  - Uses a MariaDB/MySQL database server\n  - Ideal for large-scale deployments\n  - Full-text search capabilities\n  - Better scalability and concurrency support\n  - Suitable for deployments with high load or multiple concurrent users\n\nTo switch between storage types, set the `STORAGE_TYPE` environment variable to `json`, `sqlite`, or `mariadb`.\n\nFor detailed information about storage options, including how to convert between formats, see [Storage Overview](docs/features/storage/overview.md) and [Converting Between Storage Types](docs/features/storage/converting.md).\n\n## Available Memory Tools\n\nThe Memory Graph MCP provides the following tools:\n\n### Domain Management\n\n- `select_domain`: Switch to a different memory domain\n- `list_domains`: List all available memory domains\n- `create_domain`: Create a new memory domain\n\n### Memory Operations\n\n- `store_memory`: Store new information in the memory graph\n- `recall_memories`: Retrieve memories using various strategies\n- `edit_memory`: Edit an existing memory or move it to another domain\n- `forget_memory`: Remove a memory from the graph\n\n### Visualization\n\n- `generate_mermaid_graph`: Generate a visual representation of memory relationships\n\n### Search\n\n- `search_memory_content`: Full-text search capabilities (with SQLite and MariaDB backends)\n- `traverse_memories`: Explore connections between memories across domains\n\nFor detailed information about all tools and their parameters, see the [Memory Tools Reference](docs/reference/memory-tools-reference.md).\n\n## Project Structure\n\n```\nmemory-graph/\n├── src/\n│   ├── graph/           # Knowledge graph implementation\n│   ├── storage/         # Storage backends (JSON, SQLite, MariaDB)\n│   ├── tools/           # MCP tool implementations\n│   ├── types/           # TypeScript type definitions\n│   └── index.ts         # Main server entry\n├── data/                # Memory storage (created at runtime)\n└── docs/                # Project documentation\n```\n\n## Development\n\n### Building\n\n```bash\n# Build the TypeScript code\nnpm run build\n\n# Build local Docker image\n./scripts/build-local.sh\n```\n\n### Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm test:watch\n```\n\n### Converting Between Storage Types\n\n```bash\n# Convert from JSON to SQLite\nnpx ts-node scripts/convert-storage.ts json2sqlite /path/to/json/data /path/to/sqlite/file.db\n\n# Convert from SQLite to JSON\nnpx ts-node scripts/convert-storage.ts sqlite2json /path/to/sqlite/file.db /path/to/json/data\n\n# Convert from JSON to MariaDB\nnpx ts-node scripts/convert-storage.ts json2mariadb /path/to/json/data \"mariadb://user:password@localhost:3306/memory_graph\"\n```\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fmemory-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fmemory-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fmemory-graph/lists"}