@knowall-ai/reverie 0.4.0

package/build/tools/definitions.js

@@ -0,0 +1,251 @@
+import { guidanceTool } from './guidance-tool.js';
+/**
+ * MCP Neo4j Agent Memory Tools
+ *
+ * Tool descriptions are kept simple to avoid breaking prompt templates in 3rd party solutions.
+ * Use the get_guidance tool to access detailed information about labels, relationships, and best practices.
+ */
+export const tools = [
+    {
+        name: 'search_memories',
+        description: 'Hybrid keyword + semantic search across the knowledge graph. "Ben Weeks" can also find "Benjamin Weeks" and each result includes _score and _match.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Search text to find in any property. Keyword mode matches any word, while semantic mode can surface close meanings and name variants.',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Filter by memory label',
+                },
+                depth: {
+                    type: 'integer',
+                    minimum: 0,
+                    maximum: 5,
+                    description: 'Relationship depth to include, 0 to 5, defaults to 1',
+                },
+                order_by: {
+                    type: 'string',
+                    description: 'Sort order such as created_at DESC, name ASC',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 200,
+                    description: 'Maximum results to return, 1 to 200, defaults to 10',
+                },
+                since_date: {
+                    type: 'string',
+                    description: 'ISO date string to filter memories created after this date (e.g., "2024-01-01" or "2024-01-01T00:00:00Z")',
+                },
+                search_mode: {
+                    type: 'string',
+                    enum: ['hybrid', 'keyword', 'semantic', 'exact'],
+                    description: 'Search mode: hybrid (default), keyword-only, semantic-only, or exact (case-insensitive equality on name/aliases/email: use before creating a memory).',
+                },
+                similarity_threshold: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 1,
+                    description: 'Semantic similarity threshold, 0 to 1 inclusive, defaults to 0.4.',
+                },
+                include_archived: {
+                    type: 'boolean',
+                    description: 'Include memories with status "archived" (excluded by default).',
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'create_memory',
+        description: 'Create a new memory in the knowledge graph. Consider that the memory might already exist, so Search → Create → Connect (its important to try and connect memories)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                label: {
+                    type: 'string',
+                    description: 'Memory label: a plain identifier, Capitalised singular by convention (Person, Place, Organization, Project, Event, Topic, Object, Animal, Concept, Meeting, Decision…). Use list_memory_labels first for consistency; dream canonicalises lowercase labels.',
+                },
+                properties: {
+                    type: 'object',
+                    description: 'Information to store about this memory (use "name" as primary identifier, e.g. {name: "John Smith", age: 30, occupation: "Engineer"})',
+                    additionalProperties: true,
+                },
+            },
+            required: ['label', 'properties'],
+        },
+    },
+    {
+        name: 'create_connection',
+        description: 'Create a connection between two memories (its good to have connected memories)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                fromMemoryId: {
+                    type: 'number',
+                    description: 'ID of the source memory',
+                },
+                toMemoryId: {
+                    type: 'number',
+                    description: 'ID of the target memory',
+                },
+                type: {
+                    type: 'string',
+                    description: 'Relationship type such as KNOWS, WORKS_ON, LIVES_IN, HAS_SKILL, PARTICIPATES_IN',
+                },
+                properties: {
+                    type: 'object',
+                    description: 'Optional relationship metadata (e.g. {since: "2023-01", role: "Manager", status: "active"})',
+                    additionalProperties: true,
+                },
+            },
+            required: ['fromMemoryId', 'toMemoryId', 'type'],
+        },
+    },
+    {
+        name: 'update_memory',
+        description: 'Update properties of an existing memory such as adding more detail or make a change when you find out something new',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                nodeId: {
+                    type: 'number',
+                    description: 'ID of the memory to update',
+                },
+                properties: {
+                    type: 'object',
+                    description: 'Properties to update/add',
+                    additionalProperties: true,
+                },
+            },
+            required: ['nodeId', 'properties'],
+        },
+    },
+    {
+        name: 'update_connection',
+        description: 'Update properties of an existing connection between memories',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                fromMemoryId: {
+                    type: 'number',
+                    description: 'ID of the source memory',
+                },
+                toMemoryId: {
+                    type: 'number',
+                    description: 'ID of the target memory',
+                },
+                type: {
+                    type: 'string',
+                    description: 'Relationship type to identify which connection to update (e.g. WORKS_AT, KNOWS, MANAGES)',
+                },
+                properties: {
+                    type: 'object',
+                    description: 'Properties to update/add (e.g. {status: "completed", end_date: "2024-01"})',
+                    additionalProperties: true,
+                },
+            },
+            required: ['fromMemoryId', 'toMemoryId', 'type', 'properties'],
+        },
+    },
+    {
+        name: 'delete_memory',
+        description: 'Delete a memory and all its connections (use with caution - this permanently removes the memory and all its connections)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                nodeId: {
+                    type: 'number',
+                    description: 'ID of the memory to delete',
+                },
+            },
+            required: ['nodeId'],
+        },
+    },
+    {
+        name: 'delete_connection',
+        description: 'Delete a specific connection between two memories (use with caution - this permanently removes the relationship)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                fromMemoryId: {
+                    type: 'number',
+                    description: 'ID of the source memory',
+                },
+                toMemoryId: {
+                    type: 'number',
+                    description: 'ID of the target memory',
+                },
+                type: {
+                    type: 'string',
+                    description: 'Exact relationship type to delete (e.g. WORKS_AT, KNOWS, MANAGES)',
+                },
+            },
+            required: ['fromMemoryId', 'toMemoryId', 'type'],
+        },
+    },
+    {
+        name: 'list_memory_labels',
+        description: 'List all unique memory labels currently in use with their counts (useful for getting an overview of the knowledge graph)',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                include_archived: {
+                    type: 'boolean',
+                    description: 'Include labels of archived memories (excluded by default).',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'query_memories',
+        description: 'Run a read-only Cypher query and return up to 200 scrubbed rows.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cypher: {
+                    type: 'string',
+                    description: 'Read-only Cypher to execute.',
+                },
+                params: {
+                    type: 'object',
+                    description: 'Optional parameter map for the Cypher query.',
+                    additionalProperties: true,
+                },
+            },
+            required: ['cypher'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'memory_stats',
+        description: 'Summarize node, relationship, label, embedding, and orphan counts for the graph.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'dream',
+        description: 'Deterministically relabel, merge duplicates, and refresh embeddings, with an optional dry run report.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                dry_run: {
+                    type: 'boolean',
+                    description: 'If true, report planned changes without writing them.',
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
+    guidanceTool,
+];

package/build/tools/guidance-tool.js

@@ -0,0 +1,284 @@
+export const guidanceTool = {
+    name: 'get_guidance',
+    description: 'Get help on using the memory tools effectively',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            topic: {
+                type: 'string',
+                description: 'Topic: connections, labels, relationships, best-practices, examples, or leave empty for all',
+            },
+        },
+        required: [],
+    },
+};
+export function getGuidanceContent(topic) {
+    const sections = {
+        connections: `## The Power of Connections
+
+**Why Connections Matter**
+- Isolated memories = limited utility
+- Connected memories = exponential value
+- Each connection adds context and meaning
+- Enables discovery of hidden patterns
+
+**Connection Strategy**
+1. Create the memory first
+2. Immediately ask: "What does this relate to?"
+3. Search for related memories
+4. Create meaningful connections
+5. Add properties to connections for context
+
+**Example Flow**
+1. User: "John works at Google as a software engineer"
+2. **Search for John first** - he might already exist!
+3. If not found, create memory for John (person)
+4. **Search for Google** - it probably already exists
+5. If not found, create Google (organization)
+6. Connect: John -[WORKS_AT]-> Google
+7. Add properties: role="Software Engineer", since="2020"
+
+**Connection Patterns**
+- Person -> Organization (WORKS_AT, FOUNDED, OWNS)
+- Person -> Person (KNOWS, MANAGES, MARRIED_TO)
+- Person -> Skill (HAS_SKILL)
+- Person -> Place (LIVES_IN, FROM)
+- Project -> Person (LED_BY, INVOLVES)
+- Event -> Person (ATTENDED_BY, ORGANIZED_BY)`,
+        labels: `## Common Memory Labels
+
+Use these labels when creating memories (Capitalised singular is canonical; lowercase is accepted and canonicalised by dream):
+
+**People & Living Things**
+- person: Individual people
+- animal: Pets, wildlife
+- plant: Trees, flowers, crops
+
+**Places & Locations**  
+- place: General locations
+- organization: Companies, institutions
+- vehicle: Cars, planes, boats
+
+**Concepts & Activities**
+- project: Work or personal projects
+- event: Meetings, conferences, celebrations
+- topic: Subjects of interest
+- activity: Sports, hobbies
+- skill: Abilities and expertise
+
+**Objects & Media**
+- object: Physical items
+- food: Meals, ingredients
+- media: Books, movies, music
+- document: Files, reports
+- tool: Software, hardware
+
+**Abstract Concepts**
+- idea: Thoughts, concepts
+- goal: Objectives, targets
+- task: To-dos, assignments
+- habit: Routines, behaviors
+- health: Medical, wellness`,
+        relationships: `## Common Relationship Types
+
+Use UPPERCASE for relationship types:
+
+**Personal Relationships**
+- KNOWS: General acquaintance
+- FRIENDS_WITH: Close friendship
+- MARRIED_TO: Spouse relationship
+- FAMILY_OF: Family connection
+
+**Professional Relationships**
+- WORKS_AT: Employment
+- WORKS_ON: Project involvement
+- COLLABORATES_WITH: Working together
+- MANAGES: Leadership role
+- REPORTS_TO: Reporting structure
+- OWNS: Ownership
+
+**Location Relationships**
+- LIVES_IN: Residence
+- LOCATED_IN: Physical location
+- VISITED: Past visits
+- FROM: Origin
+
+**Skill & Knowledge**
+- HAS_SKILL: Possesses ability
+- TEACHES: Instructing others
+- LEARNS_FROM: Student relationship
+
+**Project & Creation**
+- LEADS: Project leadership
+- PARTICIPATES_IN: Involvement
+- CREATED: Authorship
+- USES: Utilization`,
+        'best-practices': `## Best Practices
+
+**CRITICAL: Always Create Connections**
+- Isolated memories have limited value - ALWAYS look for connections
+- When storing new information, immediately think: "What does this relate to?"
+- A memory without connections is like a book with no catalog entry
+- The graph becomes exponentially more useful with each connection
+
+**Creating Memories - ALWAYS SEARCH FIRST**
+- **CRITICAL: Always search before creating** - memories often already exist
+- Search by name first: search_memories({query: "John Smith"})
+- If multiple matches found, **ASK THE USER TO CONFIRM** which one they mean
+- Show distinguishing details: "I found 3 people named John: John Smith (Engineer at Google), John Smith (Doctor), John Smith (Teacher). Which one did you mean?"
+- If unsure about a match, describe it and ask: "I found John Smith who works at TechCorp. Is this the same person?"
+- Only create new memory after confirming it's not a duplicate
+- Labels are plain identifiers; Capitalised singular is canonical (Person, Organization, Concept)
+- Include a 'name' property for easy identification
+- 'created_at' is automatic if not provided
+- IMMEDIATELY after creating, connect it to related memories
+
+**What belongs in the graph**
+- The graph is a map of entities and how they relate: people, organisations, projects, products, places, animals, concepts. It is not a notebook
+- A property is a durable attribute of an entity: email, role, phone, website, birthday, a preference you'd still want next year
+- Episodes (a call, an email thread, a day's events) mostly belong in your notes or diary. Store in the graph only what they taught you about an entity or a relationship, kept short
+- Prefer a relationship over a property when the fact is about two entities: Ben -[USES {note: "camera on, wants fixes verified"}]-> Teams calls, rather than a paragraph on Ben
+- Make an episode its own memory (e.g. meeting, decision) only when the episode itself is something you'll need to find again
+- A node with dozens of properties is a smell: update_memory returns a _hint past the limit, and dream lists such nodes under "bloated". When you sleep, fold each fact-like key into a short attribute, a relationship, or your notes, then remove it
+
+**Building Connections**
+- After creating any memory, ask: "What existing memories relate to this?"
+- Create connections for: people→organizations, people→projects, people→skills
+- Add relationship properties for rich context (since, role, status)
+- One memory can have many connections - don't limit yourself
+
+**Searching**
+- Empty query string returns all memories
+- Use search_mode: "hybrid" (the default) to return keyword matches first, then semantic matches above the threshold
+- Use search_mode: "keyword" to match any word of the query as a substring of any searchable content property (not timestamps, status or embedding fields), or search_mode: "semantic" for meaning-first recall
+- Use search_mode: "exact" before creating: it matches only a memory whose name, alias or email equals the query, case-insensitively
+- Archived memories are excluded unless include_archived: true
+- Lower similarity_threshold (for example 0.35) to widen semantic matches, or raise it (for example 0.7) to be stricter
+- Results include _score and _match so you can explain why something was returned
+- Use label parameter to filter by type
+- Increase depth to include more relationships (depth=2 or 3 for rich context)
+- Default limit is 10, max is 200
+
+**Managing Relationships**
+- Use UPPERCASE for relationship types
+- Add properties to relationships for context (e.g., since, role)
+- Search for memory IDs before creating connections
+- Use list_memory_labels to see existing labels
+
+**Data Organization**
+- Keep labels simple and consistent
+- Reuse existing labels when possible
+- Add descriptive properties to memories
+- Use relationships instead of complex properties
+- Think in graphs: nodes (memories) + edges (relationships) = knowledge`,
+        examples: `## Examples
+
+**Creating a Person (WITH SEARCH FIRST)**
+\`\`\`
+// ALWAYS search first to avoid duplicates
+const searchResult = search_memories({ query: "Alice Johnson" })
+
+if (searchResult.length === 0) {
+  // Only create if not found
+  create_memory({
+    label: "person",
+    properties: {
+      name: "Alice Johnson",
+      occupation: "Software Engineer",
+      company: "Tech Corp"
+    }
+  })
+} else {
+  // Use existing memory ID: searchResult[0].memory._id
+}
+\`\`\`
+
+**Creating a Relationship**
+\`\`\`
+// First, find the IDs
+search_memories({ query: "Alice Johnson" })
+search_memories({ query: "Tech Corp" })
+
+// Then connect them
+create_connection({
+  fromMemoryId: 123,
+  toMemoryId: 456,
+  type: "WORKS_AT",
+  properties: {
+    role: "Senior Engineer",
+    since: "2020-01-15"
+  }
+})
+\`\`\`
+
+**Handling Ambiguous Matches**
+\`\`\`
+// User says: "Add that Sarah works at Microsoft"
+const searchResult = search_memories({ query: "Sarah" })
+
+// Found multiple matches - ASK USER TO CONFIRM
+if (searchResult.length > 1) {
+  // Show options to user:
+  // "I found 3 people named Sarah:
+  // 1. Sarah Johnson (Marketing Manager at TechCorp)
+  // 2. Sarah Chen (Data Scientist)
+  // 3. Sarah Williams (Designer at StartupXYZ)
+  // Which Sarah works at Microsoft?"
+}
+
+// If only one match but uncertain
+if (searchResult.length === 1) {
+  // Confirm with user:
+  // "I found Sarah Johnson who is a Marketing Manager at TechCorp. 
+  // Is this the Sarah who now works at Microsoft?"
+}
+\`\`\`
+
+**Searching with Depth**
+\`\`\`
+// Find all people and their connections
+search_memories({
+  query: "",
+  label: "person",
+  depth: 2,
+  limit: 50
+})
+\`\`\`
+
+**Updating a Memory**
+\`\`\`
+update_memory({
+  nodeId: 123,
+  properties: {
+    occupation: "Lead Engineer",
+    skills: ["Python", "Neo4j", "MCP"]
+  }
+})
+\`\`\``,
+    };
+    if (!topic) {
+        // Return all sections
+        return `# Neo4j Agent Memory Guidance
+
+${sections.connections}
+
+${sections.labels}
+
+${sections.relationships}
+
+${sections['best-practices']}
+
+${sections.examples}`;
+    }
+    const content = sections[topic];
+    if (content) {
+        return content;
+    }
+    return `Unknown topic: '${topic}'. Available topics: connections, labels, relationships, best-practices, examples, or leave empty for all guidance.`;
+}
+export function isGetGuidanceArgs(args) {
+    if (typeof args !== 'object' || args === null)
+        return true; // Allow empty args
+    const obj = args;
+    return obj.topic === undefined || typeof obj.topic === 'string';
+}

package/build/types.js

@@ -0,0 +1,115 @@
+/** Labels and relationship types are interpolated into Cypher, so they must be plain identifiers. */
+export const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+export function isIdentifier(value) {
+    return typeof value === 'string' && IDENTIFIER_RE.test(value);
+}
+/** Backtick-quote a validated identifier for use in Cypher. Throws on anything not validated. */
+export function cypherIdentifier(value) {
+    if (!isIdentifier(value)) {
+        throw new Error(`Invalid Cypher identifier: ${JSON.stringify(value)}`);
+    }
+    return '`' + value + '`';
+}
+export const SEARCH_MAX_LIMIT = 200;
+export const SEARCH_MAX_DEPTH = 5;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+function isIntegerInRange(value, min, max) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max;
+}
+const isNodeId = (value) => isIntegerInRange(value, 0, Number.MAX_SAFE_INTEGER);
+export function isCreateMemoryArgs(args) {
+    return isPlainObject(args) &&
+        hasOnlyKeys(args, ['label', 'properties']) &&
+        isIdentifier(args.label) &&
+        isPlainObject(args.properties);
+}
+const SEARCH_KEYS = ['query', 'label', 'depth', 'order_by', 'limit', 'since_date', 'search_mode', 'similarity_threshold', 'include_archived'];
+export function isSearchMemoriesArgs(args) {
+    if (!isPlainObject(args) || !hasOnlyKeys(args, SEARCH_KEYS))
+        return false;
+    const searchArgs = args;
+    if (searchArgs.query !== undefined && typeof searchArgs.query !== 'string')
+        return false;
+    if (searchArgs.label !== undefined && typeof searchArgs.label !== 'string')
+        return false;
+    if (searchArgs.depth !== undefined && !isIntegerInRange(searchArgs.depth, 0, SEARCH_MAX_DEPTH))
+        return false;
+    if (searchArgs.order_by !== undefined && typeof searchArgs.order_by !== 'string')
+        return false;
+    if (searchArgs.limit !== undefined && !isIntegerInRange(searchArgs.limit, 1, SEARCH_MAX_LIMIT))
+        return false;
+    if (searchArgs.since_date !== undefined && typeof searchArgs.since_date !== 'string')
+        return false;
+    if (searchArgs.search_mode !== undefined && !['hybrid', 'keyword', 'semantic', 'exact'].includes(searchArgs.search_mode))
+        return false;
+    if (searchArgs.include_archived !== undefined && typeof searchArgs.include_archived !== 'boolean')
+        return false;
+    if (searchArgs.similarity_threshold !== undefined) {
+        const threshold = searchArgs.similarity_threshold;
+        if (typeof threshold !== 'number' || !Number.isFinite(threshold) || threshold < 0 || threshold > 1)
+            return false;
+    }
+    return true;
+}
+export function isCreateConnectionArgs(args) {
+    return isPlainObject(args) &&
+        hasOnlyKeys(args, ['fromMemoryId', 'toMemoryId', 'type', 'properties']) &&
+        isNodeId(args.fromMemoryId) &&
+        isNodeId(args.toMemoryId) &&
+        isIdentifier(args.type) &&
+        (args.properties === undefined || isPlainObject(args.properties));
+}
+export function isUpdateMemoryArgs(args) {
+    return isPlainObject(args) &&
+        hasOnlyKeys(args, ['nodeId', 'properties']) &&
+        isNodeId(args.nodeId) &&
+        isPlainObject(args.properties);
+}
+export function isUpdateConnectionArgs(args) {
+    return isPlainObject(args) &&
+        hasOnlyKeys(args, ['fromMemoryId', 'toMemoryId', 'type', 'properties']) &&
+        isNodeId(args.fromMemoryId) &&
+        isNodeId(args.toMemoryId) &&
+        isIdentifier(args.type) &&
+        isPlainObject(args.properties);
+}
+export function isDeleteMemoryArgs(args) {
+    return isPlainObject(args) && hasOnlyKeys(args, ['nodeId']) && isNodeId(args.nodeId);
+}
+export function isDeleteConnectionArgs(args) {
+    return isPlainObject(args) &&
+        hasOnlyKeys(args, ['fromMemoryId', 'toMemoryId', 'type']) &&
+        isNodeId(args.fromMemoryId) &&
+        isNodeId(args.toMemoryId) &&
+        isIdentifier(args.type);
+}
+export function isListMemoryLabelsArgs(args) {
+    return isPlainObject(args) && hasOnlyKeys(args, ['include_archived']) &&
+        (args.include_archived === undefined || typeof args.include_archived === 'boolean');
+}
+export function isQueryMemoriesArgs(args) {
+    if (!isPlainObject(args) || !hasOnlyKeys(args, ['cypher', 'params']))
+        return false;
+    const queryArgs = args;
+    if (typeof queryArgs.cypher !== 'string' || queryArgs.cypher.trim() === '')
+        return false;
+    if (queryArgs.params !== undefined && !isPlainObject(queryArgs.params))
+        return false;
+    return true;
+}
+export function isMemoryStatsArgs(args) {
+    return isPlainObject(args) && hasOnlyKeys(args, []);
+}
+export function isDreamArgs(args) {
+    if (!isPlainObject(args) || !hasOnlyKeys(args, ['dry_run']))
+        return false;
+    const dreamArgs = args;
+    if (dreamArgs.dry_run !== undefined && typeof dreamArgs.dry_run !== 'boolean')
+        return false;
+    return true;
+}