# 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