@riligar/agents-memories 1.5.1 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@riligar/agents-memories",
-    "version": "1.5.1",
+    "version": "1.5.2",
     "description": "RiLiGar Agents Memories - A self-improving relational memory system for AI agents.",
     "module": "src/index.js",
     "main": "src/index.js",

package/src/index.js

@@ -4,4 +4,4 @@ export { MemorySystem } from './sdk/memory-system.js'
 export { getSystemIdentity } from './core/identity.js'
 export * from './core/logic.js'
 export * from './database/schema.js'
-export { createMcpServer } from './server/mcp-server.js'
+export { createMcpServer } from './sdk/mcp-server.js'

package/src/sdk/mcp-server.js

@@ -0,0 +1,192 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+    ListResourcesRequestSchema,
+    ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js'
+import { createRequire } from 'module'
+import { SIP_PROTOCOL } from '../core/sip.js'
+
+const require = createRequire(import.meta.url)
+const { version } = require('../../package.json')
+
+export function createMcpServer(memorySystem) {
+    const server = new Server(
+        { name: 'RiLiGar Agents Memories', version },
+        { capabilities: { tools: {}, resources: {} } }
+    )
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [
+                {
+                    name: 'save',
+                    description: `Persists a memory to the knowledge graph for future retrieval by any agent.
+
+WHEN TO CALL: After completing a task, making a design or architectural decision, discovering a lesson learned, or receiving significant user feedback. Do not wait to be asked — save proactively.
+
+HOW TO WRITE CONTENT: Always explain WHY, not just what. Bad: "we use SQLite". Good: "we use SQLite because it runs embedded with no server, simplifying deployment and reducing infrastructure cost". The rationale is what makes the memory useful later.
+
+PATH: Organize with dot-notation (e.g., Project.Auth.Strategy, User.Preferences.Style, Lessons.Errors.Migration). Call \`list\` first to reuse an existing path instead of creating a near-duplicate.
+
+PRIORITY (0–10): 8–10 for critical decisions that must not be forgotten. 4–7 for regular notes and observations. 1–3 for minor or temporary information. High-priority saves automatically raise the priority of semantically similar neighbors.
+
+Supports batch saving: pass an array to \`content\` to persist multiple memories in one call.`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            content: {
+                                description: 'The memory to persist. Include the WHY behind the decision or lesson, not just the what. Can be a single string or an array of strings/objects for batch saving.',
+                                oneOf: [
+                                    { type: 'string' },
+                                    { type: 'array', items: { anyOf: [
+                                        { type: 'string' },
+                                        { type: 'object', properties: {
+                                            content: { type: 'string', description: 'The memory text. Include rationale.' },
+                                            path: { type: 'string', description: 'Dot-notation path (e.g., Project.Architecture.Storage).' },
+                                            owner_id: { type: 'string', description: 'Agent or user identifier.' },
+                                            priority: { type: 'integer', description: 'Importance 0–10.' }
+                                        }, required: ['content'] }
+                                    ] } }
+                                ],
+                            },
+                            path: { type: 'string', description: 'Dot-notation path categorizing this memory (e.g., Project.Backend.API, Lessons.Errors.Auth, User.Preferences). Call `list` first to reuse existing paths.' },
+                            owner_id: { type: 'string', description: 'Agent or user identifier for ownership. Use the system identity when saving on behalf of the agent itself.' },
+                            priority: { type: 'integer', description: 'Importance from 0 to 10. Use 8–10 for critical decisions, 4–7 for regular notes, 1–3 for minor observations.' },
+                        },
+                        required: ['content'],
+                    },
+                },
+                {
+                    name: 'search',
+                    description: `Semantically searches the knowledge graph and returns up to 5 results ranked by similarity (60%) and recency (40%), including any explicit relational links attached to each result.
+
+WHEN TO CALL:
+- BEFORE starting any task — to recover relevant past decisions, rationales, and lessons before acting.
+- BEFORE answering any technical question — to avoid contradicting prior decisions.
+- Whenever the user references "how we do things", "our approach", "past decisions", or when context seems to be missing.
+- After receiving an error — to check if this problem was encountered and solved before.
+- When the user asks about history, identity, preferences, values, or anything that implies continuity across sessions.
+
+Do not wait to be asked. If the task implies prior context may exist, search first.`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: { type: 'string', description: 'Natural language query describing what you are looking for (e.g., "how we handle authentication", "past errors with database migration").' },
+                            path_filter: { type: 'string', description: 'Optional path prefix to restrict results (e.g., "Project.Architecture" returns only memories under that subtree).' },
+                        },
+                        required: ['query'],
+                    },
+                },
+                {
+                    name: 'bridge',
+                    description: `Creates a directed, explicit link between two memory paths — making a logical relationship retrievable even when the contents are not semantically similar.
+
+WHEN TO CALL: When you discover that two stored topics have a dependency, hierarchy, or conflict that a semantic search would likely miss. Examples: a configuration path that depends_on an infrastructure path; a feature that implements a spec; two approaches that conflict_with each other.
+
+COMMON RELATIONS: depends_on, part_of, implements, conflicts_with, supersedes, related_to.
+
+Always call \`list\` first to confirm both paths exist. Do not bridge paths that have not been saved yet.`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            source_path: { type: 'string', description: 'The origin path of the relationship.' },
+                            target_path: { type: 'string', description: 'The destination path of the relationship.' },
+                            relation: { type: 'string', default: 'related_to', description: 'Relationship type: depends_on, part_of, implements, conflicts_with, supersedes, related_to.' },
+                        },
+                        required: ['source_path', 'target_path'],
+                    },
+                },
+                {
+                    name: 'list',
+                    description: `Returns all unique memory path names currently in the knowledge graph.
+
+WHEN TO CALL:
+- Before saving, to pick the right existing path instead of creating a near-duplicate.
+- Before bridging, to confirm the exact names of both paths.
+- When you need an overview of what knowledge domains are available before searching.`,
+                    inputSchema: { type: 'object', properties: {} },
+                },
+                {
+                    name: 'inspect',
+                    description: `Returns a Mermaid.js diagram of all explicit connections (bridges) between memory paths.
+
+WHEN TO CALL: To audit the knowledge graph structure, verify that expected relationships were recorded, or detect isolated memories with no connections. Useful after a session of saves and bridges to confirm the graph is coherent and complete.`,
+                    inputSchema: { type: 'object', properties: {} },
+                },
+            ],
+        }
+    })
+
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: [
+                {
+                    uri: 'sip://protocol',
+                    name: 'Self-Improvement Protocol (SIP)',
+                    description: 'Protocolo de autoaperfeiçoamento contínuo para agentes RiLiGar.',
+                    mimeType: 'text/markdown',
+                },
+            ],
+        }
+    })
+
+    server.setRequestHandler(ReadResourceRequestSchema, async request => {
+        if (request.params.uri === 'sip://protocol') {
+            return {
+                contents: [
+                    {
+                        uri: 'sip://protocol',
+                        mimeType: 'text/markdown',
+                        text: SIP_PROTOCOL,
+                    },
+                ],
+            }
+        }
+        throw new Error('Resource not found')
+    })
+
+    server.setRequestHandler(CallToolRequestSchema, async request => {
+        const { name, arguments: args } = request.params
+
+        try {
+            if (name === 'save') {
+                const res = await memorySystem.save(args)
+                return { content: [{ type: 'text', text: `Saved ${res.count} memories. Semantic Magnet applied.` }] }
+            }
+
+            if (name === 'bridge') {
+                await memorySystem.bridge(args)
+                return { content: [{ type: 'text', text: `Bridge created: [${args.source_path}] --(${args.relation})--> [${args.target_path}]` }] }
+            }
+
+            if (name === 'search') {
+                const rows = await memorySystem.search(args)
+                const formattedResults = rows.map(r => {
+                    const linkText = r.links.length > 0 
+                        ? `\n🔗 Related: ${r.links.map(l => `${l.path} (${l.relation_type})`).join(', ')}` 
+                        : ''
+                    return `[${r.path} | P:${r.priority}] ${r.content}${linkText}`
+                })
+                return { content: [{ type: 'text', text: formattedResults.join('\n\n') || 'No results.' }] }
+            }
+
+            if (name === 'inspect') {
+                const mermaid = await memorySystem.inspect()
+                return { content: [{ type: 'text', text: `### Knowledge Graph\n\n\`\`\`mermaid\n${mermaid}\`\`\`` }] }
+            }
+
+            if (name === 'list') {
+                const paths = await memorySystem.list()
+                return { content: [{ type: 'text', text: paths.map(p => `- ${p}`).join('\n') || 'Empty.' }] }
+            }
+
+            throw new Error('Unknown tool.')
+        } catch (error) {
+            return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
+        }
+    })
+
+    return server
+}