{"id":30805565,"url":"https://github.com/aaronsb/memory-graph-interface","last_synced_at":"2025-09-06T00:59:09.278Z","repository":{"id":288195569,"uuid":"967145719","full_name":"aaronsb/memory-graph-interface","owner":"aaronsb","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-16T14:43:27.000Z","size":1164,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-16T14:45:46.974Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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":"CONTRIBUTING.md","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-04-16T02:13:41.000Z","updated_at":"2025-05-16T14:43:30.000Z","dependencies_parsed_at":"2025-05-17T22:15:10.622Z","dependency_job_id":null,"html_url":"https://github.com/aaronsb/memory-graph-interface","commit_stats":null,"previous_names":["aaronsb/memory-graph-interface"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/memory-graph-interface","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph-interface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph-interface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph-interface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph-interface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/memory-graph-interface/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fmemory-graph-interface/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.658Z","updated_at":"2025-09-06T00:59:09.254Z","avatar_url":"https://github.com/aaronsb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Memory Graph Interface\n\nA 3D visualization interface for exploring and interacting with memory graphs created by the [memory-graph MCP](https://github.com/aaronsb/memory-graph).\n\n![Memory Graph Visualizer](docs/screenshot-nodes.png)\n\n*The Memory Graph Interface with all UI panels enabled. The visualization shows a 3D force-directed graph with nodes colored by domain, connected by labeled edges. Multiple panels provide control over visualization settings, node information, and graph navigation. The interface includes a CUA-style menu bar for easy access to all features.*\n\n## User Interface Components\n\nThe screenshot above displays the full feature set of the Memory Graph Interface:\n\n- **3D Graph Visualization**: Central force-directed graph showing memory nodes color-coded by domain with labeled relationship connections\n- **CUA Menu Bar**: Standard application menu (File, View, Visualization, Panels, Help) for easy access to all features\n- **Selected Nodes Panel**: Track and manage multiple node selections with batch operations\n- **Node Info Panel**: Detailed view of selected node content, tags, and metadata\n- **Memory Domains Panel**: Legend showing domain colors with node counts and selection tools\n- **Visualization Controls**: Advanced settings for physics simulation, rendering effects, and visual style\n- **Help Card**: Quick reference for keyboard shortcuts and mouse controls (togglable)\n- **Export/Import Features**: Domain-level data portability through the File menu\n- **Real-time Updates**: Database change indicator in menu bar with auto-refresh capability\n\nNote: Not all panels need to be visible at once - toggle them as needed through the Panels menu.\n\n## Overview\n\nMemory Graph Interface is a companion application to the [memory-graph MCP](https://github.com/aaronsb/memory-graph) which creates and manages memory nodes. This interface provides a powerful 3D visualization of memory nodes and their relationships, allowing for intuitive exploration and manipulation of the memory graph.\n\n## Demo\n\nWatch the Memory Graph Interface in action:\n\n[![Memory Graph Interface Demo](https://img.youtube.com/vi/u9EFn4BcviY/0.jpg)](https://www.youtube.com/watch?v=u9EFn4BcviY)\n\nClick the image above to watch a demonstration of the Memory Graph Interface being used in real time.\n\n## Features\n\n- **3D Force-Directed Graph**: Visualize memory nodes and their connections in an interactive 3D space\n- **Node Interaction**: Click nodes to view detailed content, add tags, and manage connections\n- **Link Creation**: Create links between nodes by shift-clicking or dragging nodes together\n- **Visual Cues**: Node sizes reflect the number of tags (larger nodes have more tags), and colors indicate domain membership\n- **Real-time Updates**: Automatically detect changes to the underlying database\n- **Visual Effects**: Toggle bloom effect for enhanced visualization\n- **Multi-domain Support**: Visualize connections across different memory domains\n- **Export/Import Domains**: Export individual memory domains as JSON files and import them to other databases\n  - Export entire domains with nodes, edges, and tags\n  - Import domains with collision handling - existing nodes get updated\n  - Cross-domain edges excluded from exports to maintain domain independence\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js (v16 or later)\n- NPM (v8 or later)\n- A compatible SQLite database created by the memory-graph MCP\n\n### Database Requirements\n\nThis application requires a SQLite database with a specific schema that matches the memory-graph MCP. Please see [database-schema.md](docs/database-schema.md) for schema details.\n\nA test database is included in the root directory for demo purposes.\n\n### Quick Start (Recommended)\n\nWe provide a setup script that handles all installation steps automatically:\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/aaronsb/memory-graph-interface.git\n   cd memory-graph-interface\n   ```\n\n2. Run the setup script:\n   ```\n   ./setup.sh\n   ```\n\n   This script will:\n   - Check system prerequisites\n   - Install dependencies\n   - Create a .env file if needed\n   - Detect and configure an available database\n   - Build the JavaScript bundle\n   - Provide helpful startup instructions\n\n3. Start the application:\n   ```\n   npm start\n   ```\n\n4. Open your browser and navigate to `http://localhost:3000`\n\n### Manual Installation\n\nIf you prefer to set up manually:\n\n1. Clone the repository:\n   ```\n   git clone https://github.com/aaronsb/memory-graph-interface.git\n   cd memory-graph-interface\n   ```\n\n2. Install dependencies:\n   ```\n   npm install\n   ```\n\n3. Build the JavaScript bundle:\n   ```\n   npm run build:js\n   ```\n\n4. Configure the database path in a `.env` file (you can copy from the example file):\n   ```\n   cp .env.example .env\n   ```\n   \n   Then edit the `.env` file to set your database path:\n   ```\n   PORT=3000\n   DB_PATH=/path/to/your/memory-graph.db\n   ```\n\n   You can use the test database included in the project by setting:\n   ```\n   DB_PATH=./memory-graph.db\n   ```\n\n5. Start the application:\n   ```\n   npm start\n   ```\n\n6. Open your browser and navigate to `http://localhost:3000`\n\n### Development Mode\n\nFor development with auto-reloading:\n\n```\nnpm run dev\n```\n\nThis will build the JavaScript bundle, start the server, and watch for changes to rebuild automatically.\n\n### Using Docker\n\nTo run the application using Docker:\n\n1. Build the Docker image:\n   ```\n   npm run docker:build\n   ```\n\n2. Start the container:\n   ```\n   npm run docker:start\n   ```\n\n3. View logs from the running container:\n   ```\n   npm run docker:logs\n   ```\n\n4. Stop the container:\n   ```\n   npm run docker:stop\n   ```\n\nBy default, Docker will look for a database at `/home/aaron/Documents/memory-graph-mcp/memory-graph.db`. You can modify this path in the `docker-compose.yml` file.\n\n## Available Scripts\n\nWe've organized the npm scripts into logical categories:\n\n### Development\n- `npm run dev` - Start development mode with auto-reloading\n- `npm run watch` - Run webpack in watch mode\n- `npm run server` - Start only the Express server\n\n### Production\n- `npm start` - Build JS and start the server\n- `npm run build` - Build JS in production mode\n\n### Docker\n- `npm run docker:build` - Build the Docker image\n- `npm run docker:start` - Start the Docker container\n- `npm run docker:stop` - Stop the Docker container\n- `npm run docker:logs` - View container logs\n\nFor more details on contributing to this project, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Usage\n\n- **View Node Details**: Click on a node to see its content and tags\n- **Create Links**: Shift-click two nodes to create a link between them\n- **Drag to Link**: Drag a node near another to automatically create a link\n- **Delete Links**: Control-click on a link to delete it\n- **Delete Nodes**: Control-click on a node to delete it and all its connections\n- **Add Tags**: Select a node and use the tag input field to add new tags\n- **Refresh Data**: Click the \"Refresh Data\" button to manually update the visualization\n- **Toggle Effects**: Use the \"Toggle Bloom\" button to enable/disable the bloom visual effect\n- **Select Database**: In the File menu, select \"Open Database\" to choose a different database file using the file browser\n- **Export Domain**: \n  - From the File menu, select \"Export Domain...\"\n  - Choose a domain from the dropdown list\n  - Click Export to download the domain as a JSON file\n  - Alternatively, click the 📥 icon next to any domain in the Memory Domains panel\n- **Import Domain**:\n  - From the File menu, select \"Import Domain...\"\n  - Choose a JSON file exported from Memory Graph\n  - Review the import preview showing nodes and edges\n  - Click Import to add the domain to your current database\n  - Existing nodes will be updated, new nodes will be created\n\n## Multi-Agent Support\n\nThe Memory Graph Interface can be used by multiple agents simultaneously, all accessing the same memory database. This allows for collaborative memory management and exploration across different AI systems.\n\n## Database Selection\n\nThe application provides a file browser interface for selecting SQLite database files:\n\n1. Click **File** in the menu bar, then select **Open Database**\n2. You can either:\n   - Type a full path manually in the input field\n   - Use the **Browse** button to open the file browser\n   - Select from previously used database paths using the dropdown\n\nUsing the file browser:\n- Navigate through directories by clicking on folder names\n- Filter files to only show `.db` SQLite database files\n- Click once on a file to select it\n- Double-click a file to select and confirm it immediately\n- Use the **Parent Directory** button to go up a level\n- Use the **Refresh** button to reload the current directory\n\nAfter selecting a database, click **Confirm** to load it into the application.\n\n## Troubleshooting\n\n- **Database Errors**: If you see errors like \"no such table: MEMORY_NODES\", ensure your database has the correct schema. See [database-schema.md](docs/database-schema.md) for details.\n- **JavaScript Not Loading**: If the visualization doesn't appear, make sure you've built the JavaScript bundle with `npm run build:js`.\n- **Docker Issues**: If using Docker, ensure the volume path in `docker-compose.yml` points to a valid directory with your database file.\n- **File Browser Not Working**: If the file browser doesn't load directories correctly, check server permissions on the directories you're trying to access.\n\n## Related Projects\n\n- [memory-graph MCP](https://github.com/aaronsb/memory-graph): The MCP server that creates and manages the memory nodes visualized by this interface\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fmemory-graph-interface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fmemory-graph-interface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fmemory-graph-interface/lists"}