How j3k0/mcp-brain-tools works
Main Components
• AI Conversation Memory Service – This is the core of the system that handles storing, updating, and retrieving conversation data.
• Knowledge Graph Engine – Represented by components (e.g., kg-client.ts, kg-inspection.ts) that manage entities and relationships.
• Elasticsearch Backend – The project relies on Elasticsearch (as noted by the badge and README) for persistent storage and smart search capabilities.
• Admin CLI Tools – Modules such as admin-cli.ts provide a command-line interface to manage the graph (search, backup, zone creation, etc.).
• Filesystem Module – Indicated in the src/filesystem directory, this likely manages file-based operations related to data ingestion or storage handling.
• Logger – The logger.ts helps in tracking and recording activities, which is crucial for debugging and monitoring.
• Legacy Components – The legacy folder contains older CLI utilities and test scripts which can be shown as legacy modules that might still interact with or influence the current system.
Relationships and Interactions
• Data Flow: Show how an incoming AI conversation or entity update flows from the AI service (ai-service.ts) into the knowledge graph and then is stored in Elasticsearch. Then, how search queries or memory recall requests traverse back from Elasticsearch to the AI service.
• Admin Operations: Indicate that the Admin CLI (admin-cli.ts) interacts directly with the Knowledge Graph Engine and Elasticsearch for maintenance tasks like search, entity lookup, backup, and zone management.
• Filesystem Interactions: Illustrate how the filesystem module might be used for import/export operations (e.g., loading JSON data or processing local files).
• Legacy Processing: Optionally, include how legacy modules provide support or backward compatibility and interact with updated modules.
Architectural Patterns and Design Principles
• Service-Oriented/Modular Design: Emphasize that components such as AI service logic, filesystem operations, and admin tools are separated into distinct modules. This modularity supports easier testing and extensibility.
• Client-Server Interaction: While there isn’t a separate frontend, the interaction flow from Claude Desktop (via the launch script/CLI integration) to the memory service can be captured.
• Layered Architecture: Separate the business logic (memory processing, entity creation/updates) from infrastructural specifics like connecting with Elasticsearch.
• Dependency & Integration: Highlight Node.js (as the runtime), and note that Docker and docker-compose files indicate containerized deployment for Elasticsearch and possibly for the service itself.
Relevant Technologies
• Node.js (version 18+)
• Elasticsearch (version 7.x)
• Docker & Docker Compose (for running Elasticsearch)
• Testing frameworks (Jest and Vitest as seen by jest.config and vitest.config)
• Annotations or notes about key functionalities such as “Contextual Recall”, “Entity Management”, and “Memory Zones” that highlight how the service differentiates between short-term and long-term memory.