DevFlow MCP

# DevFlow MCP: Smart Memory for AI Agents Ever wished your AI could remember things between conversations? DevFlow MCP gives any AI that supports the Model Context Protocol (like Claude Desktop) a persistent, searchable memory that actually makes sense. Think of it as giving your AI a brain that doesn't reset every time you start a new chat. ## What Makes This Different? Most AI memory systems are either too complex to set up or too simple to be useful. DevFlow MCP hits the sweet spot: **Actually Works Out of the Box**: No Docker containers, no external databases to configure. Just install and run. **Built for Real Development**: Created by developers who got tired of explaining the same context over and over to AI assistants. This system understands how software projects actually work. **Honest About What It Does**: Every feature documented here actually exists and works. No promises about features "coming soon" or half-implemented APIs. **Type-Safe Throughout**: Zero `any` types in the entire codebase. If TypeScript is happy, the code works. ## The Story Behind This Project This started as a simple problem: AI assistants kept forgetting important project context between sessions. Existing solutions were either enterprise-grade overkill or toy projects that couldn't handle real workloads. So we built something that actually solves the problem. DevFlow MCP has been battle-tested on real projects, handling everything from quick prototypes to complex enterprise applications. --- ## Core Concepts ### Entities Entities are the primary nodes in the knowledge graph. Each entity has: - A unique name (identifier) - An entity type (e.g., "person", "organization", "event") - A list of observations - Vector embeddings (for semantic search) - Complete version history Example: ```json { "name": "John_Smith", "entityType": "person", "observations": ["Speaks fluent Spanish"] } ``` ### Relations Relations define directed connections between entities with enhanced properties: - Strength indicators (0.0-1.0) - Confidence levels (0.0-1.0) - Rich metadata (source, timestamps, tags) - Temporal awareness with version history - Time-based confidence decay Example: ```json { "from": "John_Smith", "to": "Anthropic", "relationType": "works_at", "strength": 0.9, "confidence": 0.95, "metadata": { "source": "linkedin_profile", "last_verified": "2025-03-21" } } ``` ### Prompts (Workflow Guidance) DevFlow MCP includes **workflow-aware prompts** that teach AI agents how to use the knowledge graph effectively in a cascading development workflow (planner → task creator → coder → reviewer). **What are prompts?** Prompts are instructional messages that guide AI agents on which tools to call and when. They appear as slash commands in Claude Desktop (e.g., `/init-project`) and provide context-aware documentation. **Important:** Prompts don't save data themselves—they return guidance text that tells the AI which tools to call. The AI then calls those tools (like `create_entities`, `semantic_search`) which actually interact with the database. #### Available Prompts ##### 1. `/init-project` - Start New Projects Guides planners on creating initial feature entities and structuring planning information. **Arguments:** - `projectName` (required): Name of the project or feature - `description` (required): High-level description - `goals` (optional): Specific goals or requirements **What it teaches:** - How to create "feature" entities for high-level projects - How to document decisions early - How to plan tasks and link them to features - Best practices for structuring project information **Example usage in Claude Desktop:** ``` /init-project projectName="UserAuthentication" description="Implement secure user login system" goals="Support OAuth, 2FA, and password reset" ``` ##### 2. `/get-context` - Retrieve Relevant Information Helps any agent search the knowledge graph for relevant history, dependencies, and context before starting work. **Arguments:** - `query` (required): What are you working on? (used for semantic search) - `entityTypes` (optional): Filter by types (feature, task, decision, component, test) - `includeHistory` (optional): Include version history (default: false) **What it teaches:** - How to use semantic search to find related work - How to check dependencies via relations - How to review design decisions - How to understand entity version history **Example usage:** ``` /get-context query="authentication implementation" entityTypes=["component","decision"] includeHistory=true ``` ##### 3. `/remember-work` - Store Completed Work Guides agents on saving their work with appropriate entity types and relations. **Arguments:** - `workType` (required): Type of work (feature, task, decision, component, test) - `name` (required): Name/title of the work - `description` (required): What did you do? (stored as observations) - `implementsTask` (optional): Task this work implements (creates "implements" relation) - `partOfFeature` (optional): Feature this is part of (creates "part_of" relation) - `dependsOn` (optional): Components this depends on (creates "depends_on" relations) - `keyDecisions` (optional): Important decisions made **What it teaches:** - How to create entities with correct types - How to set up relations between entities - How to document decisions separately - How to maintain the knowledge graph structure **Example usage:** ``` /remember-work workType="component" name="AuthService" description="Implemented OAuth login flow with JWT tokens" implementsTask="UserAuth" partOfFeature="Authentication" dependsOn=["TokenManager","UserDB"] ``` ##### 4. `/review-context` - Get Full Review Context Helps reviewers gather all relevant information about a piece of work before providing feedback. **Arguments:** - `entityName` (required): Name of the entity to review - `includeRelated` (optional): Include related entities (default: true) - `includeDecisions` (optional): Include decision history (default: true) **What it teaches:** - How to get the entity being reviewed - How to find related work (dependencies, implementations) - How to review design decisions - How to check test coverage - How to add review feedback as observations **Example usage:** ``` /review-context entityName="AuthService" includeRelated=true includeDecisions=true ``` #### Cascading Workflow Example Here's how prompts guide a complete development workflow: **1. Planner Agent:** ``` /init-project projectName="UserDashboard" description="Create user analytics dashboard" # AI learns to create feature entity, plan tasks ``` **2. Task Creator Agent:** ``` /get-context query="dashboard features" # AI learns to search for related work, then creates task entities ``` **3. Developer Agent:** ``` /get-context query="dashboard UI components" # AI learns to find relevant components and decisions /remember-work workType="component" name="DashboardWidget" description="Created widget framework" # AI learns to store work with proper relations ``` **4. Reviewer Agent:** ``` /review-context entityName="DashboardWidget" # AI learns to get full context, check tests, add feedback ``` #### Why Prompts Matter - **Consistency**: All agents use the same structured approach - **Context preservation**: Work is stored with proper metadata and relations - **Discoverability**: Future agents can find relevant history via semantic search - **Workflow awareness**: Each prompt knows its place in the development cycle - **Self-documenting**: Prompts teach agents best practices ## How It Works Under the Hood DevFlow MCP stores everything in a single SQLite database file. Yes, really - just one file on your computer. ### Why SQLite Instead of Something "Fancier"? We tried the complex stuff first. External databases, Docker containers, cloud services - they all work, but they're overkill for what most developers actually need. SQLite gives you: - **One file to rule them all**: Your entire knowledge graph lives in a single `.db` file you can copy, backup, or version control - **No setup headaches**: No servers to configure, no containers to manage, no cloud accounts to create - **Surprisingly fast**: SQLite handles millions of records without breaking a sweat - **Vector search built-in**: The sqlite-vec extension handles semantic search natively - **Works everywhere**: From your laptop to production servers, SQLite just works ### Getting Started (It's Ridiculously Simple) ```bash # Install globally npm install -g devflow-mcp # Run it (creates database automatically) dfm mcp # Want to use a specific file? Set the location DFM_SQLITE_LOCATION=./my-project-memory.db dfm mcp ``` No configuration files. No environment setup. No "getting started" tutorials that take 3 hours. It just works. **Requirements**: Node.js 23+ (for the latest SQLite features) ## Advanced Features ### Semantic Search Find semantically related entities based on meaning rather than just keywords: - **Vector Embeddings**: Entities are automatically encoded into high-dimensional vector space using OpenAI's embedding models - **Cosine Similarity**: Find related concepts even when they use different terminology - **Configurable Thresholds**: Set minimum similarity scores to control result relevance - **Cross-Modal Search**: Query with text to find relevant entities regardless of how they were described - **Multi-Model Support**: Compatible with multiple embedding models (OpenAI text-embedding-3-small/large) - **Contextual Retrieval**: Retrieve information based on semantic meaning rather than exact keyword matches - **Optimized Defaults**: Tuned parameters for balance between precision and recall (0.6 similarity threshold, hybrid search enabled) - **Hybrid Search**: Combines semantic and keyword search for more comprehensive results - **Adaptive Search**: System intelligently chooses between vector-only, keyword-only, or hybrid search based on query characteristics and available data - **Performance Optimization**: Prioritizes vector search for semantic understanding while maintaining fallback mechanisms for resilience - **Query-Aware Processing**: Adjusts search strategy based on query complexity and available entity embeddings ### Temporal Awareness Track complete history of entities and relations with point-in-time graph retrieval: - **Full Version History**: Every change to an entity or relation is preserved with timestamps - **Point-in-Time Queries**: Retrieve the exact state of the knowledge graph at any moment in the past - **Change Tracking**: Automatically records createdAt, updatedAt, validFrom, and validTo timestamps - **Temporal Consistency**: Maintain a historically accurate view of how knowledge evolved - **Non-Destructive Updates**: Updates create new versions rather than overwriting existing data - **Time-Based Filtering**: Filter graph elements based on temporal criteria - **History Exploration**: Investigate how specific information changed over time ### Confidence Decay Relations automatically decay in confidence over time based on configurable half-life: - **Time-Based Decay**: Confidence in relations naturally decreases over time if not reinforced - **Configurable Half-Life**: Define how quickly information becomes less certain (default: 30 days) - **Minimum Confidence Floors**: Set thresholds to prevent over-decay of important information - **Decay Metadata**: Each relation includes detailed decay calculation information - **Non-Destructive**: Original confidence values are preserved alongside decayed values - **Reinforcement Learning**: Relations regain confidence when reinforced by new observations - **Reference Time Flexibility**: Calculate decay based on arbitrary reference times for historical analysis ### Advanced Metadata Rich metadata support for both entities and relations with custom fields: - **Source Tracking**: Record where information originated (user input, analysis, external sources) - **Confidence Levels**: Assign confidence scores (0.0-1.0) to relations based on certainty - **Relation Strength**: Indicate importance or strength of relationships (0.0-1.0) - **Temporal Metadata**: Track when information was added, modified, or verified - **Custom Tags**: Add arbitrary tags for classification and filtering - **Structured Data**: Store complex structured data within metadata fields - **Query Support**: Search and filter based on metadata properties - **Extensible Schema**: Add custom fields as needed without modifying the core data model ## MCP API Tools The following tools are available to LLM client hosts through the Model Context Protocol: ### Entity Management - **create_entities** - Create multiple new entities in the knowledge graph - Input: `entities` (array of objects) - Each object contains: - `name` (string): Entity identifier - `entityType` (string): Type classification - `observations` (string[]): Associated observations - **add_observations** - Add new observations to existing entities - Input: `observations` (array of objects) - Each object contains: - `entityName` (string): Target entity - `contents` (string[]): New observations to add - Note: Unlike relations, observations do not support strength, confidence, or metadata fields. Observations are atomic facts about entities. - **delete_entities** - Remove entities and their relations - Input: `entityNames` (string[]) - **delete_observations** - Remove specific observations from entities - Input: `deletions` (array of objects) - Each object contains: - `entityName` (string): Target entity - `observations` (string[]): Observations to remove ### Relation Management - **create_relations** - Create multiple new relations between entities with enhanced properties - Input: `relations` (array of objects) - Each object contains: - `from` (string): Source entity name - `to` (string): Target entity name - `relationType` (string): Relationship type - `strength` (number, optional): Relation strength (0.0-1.0) - `confidence` (number, optional): Confidence level (0.0-1.0) - `metadata` (object, optional): Custom metadata fields - **get_relation** - Get a specific relation with its enhanced properties - Input: - `from` (string): Source entity name - `to` (string): Target entity name - `relationType` (string): Relationship type - **update_relation** - Update an existing relation with enhanced properties - Input: `relation` (object): - Contains: - `from` (string): Source entity name - `to` (string): Target entity name - `relationType` (string): Relationship type - `strength` (number, optional): Relation strength (0.0-1.0) - `confidence` (number, optional): Confidence level (0.0-1.0) - `metadata` (object, optional): Custom metadata fields - **delete_relations** - Remove specific relations from the graph - Input: `relations` (array of objects) - Each object contains: - `from` (string): Source entity name - `to` (string): Target entity name - `relationType` (string): Relationship type ### Graph Operations - **read_graph** - Read the entire knowledge graph - No input required - **search_nodes** - Search for nodes based on query - Input: `query` (string) - **open_nodes** - Retrieve specific nodes by name - Input: `names` (string[]) ### Semantic Search - **semantic_search** - Search for entities semantically using vector embeddings and similarity - Input: - `query` (string): The text query to search for semantically - `limit` (number, optional): Maximum results to return (default: 10) - `min_similarity` (number, optional): Minimum similarity threshold (0.0-1.0, default: 0.6) - `entity_types` (string[], optional): Filter results by entity types - `hybrid_search` (boolean, optional): Combine keyword and semantic search (default: true) - `semantic_weight` (number, optional): Weight of semantic results in hybrid search (0.0-1.0, default: 0.6) - Features: - Intelligently selects optimal search method (vector, keyword, or hybrid) based on query context - Gracefully handles queries with no semantic matches through fallback mechanisms - Maintains high performance with automatic optimization decisions - **get_entity_embedding** - Get the vector embedding for a specific entity - Input: - `entity_name` (string): The name of the entity to get the embedding for ### Temporal Features - **get_entity_history** - Get complete version history of an entity - Input: `entityName` (string) - **get_relation_history** - Get complete version history of a relation - Input: - `from` (string): Source entity name - `to` (string): Target entity name - `relationType` (string): Relationship type - **get_graph_at_time** - Get the state of the graph at a specific timestamp - Input: `timestamp` (number): Unix timestamp (milliseconds since epoch) - **get_decayed_graph** - Get graph with time-decayed confidence values - Input: `options` (object, optional): - `reference_time` (number): Reference timestamp for decay calculation (milliseconds since epoch) - `decay_factor` (number): Optional decay factor override ## Configuration ### Environment Variables Configure DevFlow MCP with these environment variables: ```bash # SQLite Configuration DFM_SQLITE_LOCATION=./knowledge.db # Embedding Service Configuration OPENAI_API_KEY=your-openai-api-key OPENAI_EMBEDDING_MODEL=text-embedding-3-small # Debug Settings DEBUG=true ``` ### Embedding Models Available OpenAI embedding models: - `text-embedding-3-small`: Efficient, cost-effective (1536 dimensions) - `text-embedding-3-large`: Higher accuracy, more expensive (3072 dimensions) - `text-embedding-ada-002`: Legacy model (1536 dimensions) #### OpenAI API Configuration To use semantic search, you'll need to configure OpenAI API credentials: 1. Obtain an API key from [OpenAI](https://platform.openai.com/api-keys) 2. Configure your environment with: ```bash # OpenAI API Key for embeddings OPENAI_API_KEY=your-openai-api-key # Default embedding model OPENAI_EMBEDDING_MODEL=text-embedding-3-small ``` > **Note**: For testing environments, the system will mock embedding generation if no API key is provided. However, using real embeddings is recommended for integration testing. ## Integration with Claude Desktop ### Configuration For local development, add this to your `claude_desktop_config.json`: ```json { "mcpServers": { "devflow": { "command": "dfm", "args": ["mcp"], "env": { "DFM_SQLITE_LOCATION": "./knowledge.db", "OPENAI_API_KEY": "your-openai-api-key", "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small", "DEBUG": "true" } } } } ``` > **Important**: Always explicitly specify the embedding model in your Claude Desktop configuration to ensure consistent behavior. ### Recommended System Prompts For optimal integration with Claude, add these statements to your system prompt: ``` You have access to the DevFlow MCP knowledge graph memory system, which provides you with persistent memory capabilities. Your memory tools are provided by DevFlow MCP, a sophisticated knowledge graph implementation. When asked about past conversations or user information, always check the DevFlow MCP knowledge graph first. You should use semantic_search to find relevant information in your memory when answering questions. ``` ### Testing Semantic Search Once configured, Claude can access the semantic search capabilities through natural language: 1. To create entities with semantic embeddings: ``` User: "Remember that Python is a high-level programming language known for its readability and JavaScript is primarily used for web development." ``` 2. To search semantically: ``` User: "What programming languages do you know about that are good for web development?" ``` 3. To retrieve specific information: ``` User: "Tell me everything you know about Python." ``` The power of this approach is that users can interact naturally, while the LLM handles the complexity of selecting and using the appropriate memory tools. ### Real-World Applications DevFlow MCP's adaptive search capabilities provide practical benefits: 1. **Query Versatility**: Users don't need to worry about how to phrase questions - the system adapts to different query types automatically 2. **Failure Resilience**: Even when semantic matches aren't available, the system can fall back to alternative methods without user intervention 3. **Performance Efficiency**: By intelligently selecting the optimal search method, the system balances performance and relevance for each query 4. **Improved Context Retrieval**: LLM conversations benefit from better context retrieval as the system can find relevant information across complex knowledge graphs For example, when a user asks "What do you know about machine learning?", the system can retrieve conceptually related entities even if they don't explicitly mention "machine learning" - perhaps entities about neural networks, data science, or specific algorithms. But if semantic search yields insufficient results, the system automatically adjusts its approach to ensure useful information is still returned. ## Troubleshooting ### Vector Search Diagnostics DevFlow MCP includes built-in diagnostic capabilities to help troubleshoot vector search issues: - **Embedding Verification**: The system checks if entities have valid embeddings and automatically generates them if missing - **Vector Index Status**: Verifies that the vector index exists and is in the ONLINE state - **Fallback Search**: If vector search fails, the system falls back to text-based search - **Detailed Logging**: Comprehensive logging of vector search operations for troubleshooting ### Debug Tools (when DEBUG=true) Additional diagnostic tools become available when debug mode is enabled: - **diagnose_vector_search**: Information about the SQLite vector index, embedding counts, and search functionality - **force_generate_embedding**: Forces the generation of an embedding for a specific entity - **debug_embedding_config**: Information about the current embedding service configuration ### Developer Reset To completely reset your SQLite database during development: ```bash # Remove the database file rm -f ./knowledge.db # Or if using a custom location rm -f $DFM_SQLITE_LOCATION # Restart your application - schema will be recreated automatically dfm mcp ``` ## Building and Development ```bash # Clone the repository git clone https://github.com/takinprofit/dev-flow-mcp.git cd dev-flow-mcp # Install dependencies (uses pnpm, not npm) pnpm install # Build the project pnpm run build # Run tests pnpm test # Check test coverage pnpm run test:coverage # Type checking npx tsc --noEmit # Linting npx ultracite check src/ npx ultracite fix src/ ``` ## Installation ### Local Development For development or contributing to the project: ```bash # Clone the repository git clone https://github.com/takinprofit/dev-flow-mcp.git cd dev-flow-mcp # Install dependencies pnpm install # Build the CLI pnpm run build # The CLI will be available as 'dfm' command ``` ## License MIT