@riligar/agents-memories 1.0.0 → 1.2.0

package/README.md

@@ -1,78 +1,110 @@
 # RiLiGar Agents Memories
 
-A high-performance, persistent memory system for AI agents, built on the **Model Context Protocol (MCP)**. This project implements a **Relational Knowledge Graph** featuring **Resonance Intelligence** and **Semantic Bridging**.
+A high-performance, persistent memory system for AI agents, built on the **Model Context Protocol (MCP)**. RiLiGar transforms flat data into a **Relational Knowledge Graph** featuring **Resonance Intelligence** and **Semantic Bridging**.
 
-## 🧠 Philosophy: The Cognitive Memories
+Now evolved into a **Modular SDK**, RiLiGar can be used both as a standalone MCP server and as a core library for cognitive applications.
 
-> "The original repository is a developer's **Toolbox**; our project are the **Collective Memories** for AIs. We evolved the fixed hierarchy into a self-organizing, relational mind. 🏛✨"
+## 🧠 Philosophy: The Cognitive Self
 
-RiLiGar focuses on **Relational Intelligence**. By transforming memories into a living graph, the agent doesn't just retrieve facts—it understands how those facts are interconnected across different domains.
+RiLiGar focuses on **Relational Intelligence**. Memory is not just retrieval; it is an extension of the agent's identity. By transforming memories into a living graph, the agent understands how facts are interconnected across different domains, simulating a "working memory" that evolves with every interaction.
 
-## 🛡️ Cryptographic Identity
-
-Each RiLiGar installation possesses a unique, professional cryptographic identity (Ed25519):
+---
 
-- **Implicit Ownership**: By default, the system uses its own 10-character hex ID (derived from the public key hash) to sign and own memories.
-- **Explicit Identity**: Users or external agents can provide their own `owner_id` to maintain clear boundaries in multi-user environments.
-- **Architecture**: Stored locally in `data/identity.json`, ensuring the agent maintains its "soul" across sessions.
+## 🏗️ Modular Architecture
 
-## 🕸 The Relational Knowledge Graph
+The project is organized into distinct layers to ensure scalability and maintainability:
 
-RiLiGar moves beyond simple keyword or vector storage into a **Graph Database** paradigm:
+- **`src/core` (Cognition)**: Implements the heavy-lifting logic:
+    - **Resonance Intelligence**: Priorities ripple through the graph; if a node is marked as critical, its semantic neighbors gain importance.
+    - **Semantic Magnet**: Automatically detects near-identical facts and creates `similar_to` links.
+- **`src/database` (Persistence)**: Uses **LibSQL (SQLite)** for edge-ready, high-speed storage.
+- **`src/sdk` (Interface)**: Provides the `MemorySystem` class, a clean programmatic API.
+- **`src/server` (Transport)**: Handles MCP communication via **Stdio** (local) and **SSE** (web/remote).
 
-- **Semantic Magnet (Auto-Bridging)**: The system automatically detects near-identical facts (similarity > 0.9) and creates `similar_to` links during the storage phase.
-- **Manual Bridging**: Explicitly connect disparate paths using the `bridge` tool to establish logical dependencies (e.g., `Architecture` depends_on `Infrastructure`).
-- **Resonance Intelligence**: Priorities ripple through the graph; if a node is marked as critical, its semantic neighbors gain importance via resonance.
+---
 
-## 🏺 Visualizing the Memories
+## 🔌 Quick Start
 
-RiLiGar provides a native **Inspection** layer using **Mermaid.js**:
+### Prerequisites
 
-- **Command**: `inspect`
-- **Output**: Generates a visual mental map of all connections, allowing the agent and user to see the topology of their stored knowledge.
+- [Bun](https://bun.sh) runtime (v1.x+)
 
-## ⚖️ Relational Semantic Search
+### Installation
 
-Searches in RiLiGar are **Read-Only** and **Relational**. When a fact is retrieved, its connections are automatically surfaced:
+```bash
+bun install
+```
 
-`[Path.A | P:10] Fact A`
-`🔗 Related: Path.B (similar_to), Path.C (depends_on)`
+### Running the Standalone Server
 
-- **Scoring (Working Memory Boost)**: `Score = (Similarity * 0.6) + (Recency * 0.4)`.
-- **Short-term Awareness**: The system is tuned for **Cognitive Fluidity**, prioritizing recent thoughts and context to function as an effective short-term "working memory" while maintaining long-term relational links.
+The server starts both **Stdio** and **SSE** transports simultaneously on port `3000`.
 
-## 🔌 MCP Tools
+```bash
+bun start
+```
 
-- `save`: Stores content with automatic priority inference and **Semantic Magnet** auto-linking.
-- `search`: Executes a fast, weighted relational semantic search.
-- `bridge`: Manually links two memory paths with a specified relation type.
-- `inspect`: Generates a Mermaid.js diagram of the current knowledge graph.
-- `list`: Lists all unique memory paths.
+- **Stdio**: Use this for Claude Desktop or local IDE configurations.
+- **SSE**: Access via `http://localhost:3000/sse` for web dashboards or remote agents.
 
 ---
 
-## 🛠️ Setup & Usage
+## 📦 Programmatic Usage (SDK)
 
-### Prerequisites
+You can use RiLiGar as a library in your own Bun projects:
 
-- [Bun](https://bun.sh) runtime (v1.x+)
+```javascript
+import { MemorySystem, getSystemIdentity } from '@riligar/agents-memories'
+import { createClient } from '@libsql/client'
 
-### Installation
+const db = createClient({ url: 'file:data/memories.db' })
+const ownerId = getSystemIdentity('data')
 
-```bash
-bun install
-```
+const memory = new MemorySystem(db, ownerId)
+await memory.init()
 
-### Running the Server
+// Save a memory with automatic priority inference
+await memory.save({
+    content: 'The architecture is now modular.',
+    path: 'Project.Architecture',
+})
 
-```bash
-bun start # runs src/index.js
+// Relational Semantic Search
+const results = await memory.search({ query: 'How is the project organized?' })
+console.log(results)
 ```
 
-### Verification
+---
+
+## 🛡️ Identity & SaaS Readiness
+
+- **Cryptographic Soul**: Each installation generates an Ed25519 identity (`data/identity.json`). The system uses a 10-character hex `owner_id` derived from this key.
+- **Multi-Tenancy**: Every memory is bound to an `owner_id`, allowing the same database to securely host memories for multiple users or agents.
+
+---
+
+## 🛠️ MCP Tools Reference
+
+- `save`: Stores content with automatic priority inference and **Semantic Magnet** auto-linking.
+- `search`: Relational semantic search (Score = 60% Similarity + 40% Recency).
+- `bridge`: Manually links two memory paths (e.g., `Architecture` -> `Security`).
+- `inspect`: Generates a **Mermaid.js** graph of the memory topology.
+- `list`: Shows all unique memory paths.
+
+---
+
+## 🧪 Development
+
+### Running tests
 
 ```bash
-bun src/test.js
+bun test
 ```
 
-**Built with ❤️ for the global open-source community by the RiLiGar Team.**
+### Stack
+
+- **Runtime**: [Bun](https://bun.sh)
+- **Database**: [LibSQL](https://github.com/tursodatabase/libsql)
+- **Embeddings**: [Transformers.js](https://huggingface.co/docs/transformers.js) (`all-MiniLM-L6-v2`)
+- **Server**: [Express](https://expressjs.com/) + MCP SDK
+
+**Built with ❤️ by the RiLiGar Team.**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@riligar/agents-memories",
-    "version": "1.0.0",
-    "description": "RiLiGar Agents Memories - A persistent memories system for AI agents.",
+    "version": "1.2.0",
+    "description": "RiLiGar Agents Memories - A self-improving relational memory system for AI agents.",
     "module": "src/index.js",
     "main": "src/index.js",
     "type": "module",
@@ -23,10 +23,9 @@
     },
     "homepage": "https://github.com/riligar/agents-memories#readme",
     "scripts": {
-        "dev": "bun --watch src/index.js",
-        "start": "bun src/index.js",
-        "test": "bun src/test.js",
-        "test:sse": "bun src/test-sse.js"
+        "dev": "bun --watch src/server/index.js",
+        "start": "bun src/server/index.js",
+        "test": "bun src/test.js"
     },
     "dependencies": {
         "@huggingface/transformers": "^4.0.1",

package/src/core/identity.js

@@ -0,0 +1,33 @@
+import fs from 'fs'
+import path from 'path'
+import crypto from 'crypto'
+
+/**
+ * Utilitário para gerenciar a identidade criptográfica do agente.
+ */
+export function getSystemIdentity(dataDir) {
+    const identityPath = path.join(dataDir, 'identity.json')
+    
+    if (fs.existsSync(identityPath)) {
+        const data = JSON.parse(fs.readFileSync(identityPath, 'utf8'))
+        return data.owner_id
+    }
+
+    if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true })
+
+    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
+    })
+
+    const ownerId = crypto.createHash('sha256').update(publicKey).digest('hex').substring(0, 10)
+
+    fs.writeFileSync(identityPath, JSON.stringify({
+        owner_id: ownerId,
+        public_key: publicKey,
+        private_key: privateKey
+    }, null, 2), 'utf8')
+
+    console.error(`Generated new cryptographic identity: ${ownerId}`)
+    return ownerId
+}

package/src/core/logic.js

@@ -0,0 +1,62 @@
+import { pipeline } from '@huggingface/transformers'
+
+let extractor = null
+
+/**
+ * Gera embeddings para o texto fornecido.
+ */
+export async function getEmbedding(text) {
+    if (!extractor) {
+        extractor = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2')
+    }
+    const output = await extractor(text, { pooling: 'mean', normalize: true })
+    return new Float32Array(output.data)
+}
+
+/**
+ * Infere a prioridade biológica/semântica com base na vizinhança.
+ */
+export async function inferPriority(db, vector) {
+    const result = await db.execute({
+        sql: `SELECT priority, vector_distance_cos(embedding, ?) as distance FROM memories ORDER BY distance ASC LIMIT 5`,
+        args: [vector.buffer],
+    })
+    if (result.rows.length === 0) return 5
+    let weightedSum = 0,
+        totalWeight = 0
+    for (const row of result.rows) {
+        const similarity = 1 - row.distance
+        const weight = Math.pow(similarity, 2)
+        weightedSum += row.priority * weight
+        totalWeight += weight
+    }
+    return totalWeight > 0 ? Math.round(weightedSum / totalWeight) : 5
+}
+
+/**
+ * Propaga o impacto (ressonância) para memórias vizinhas.
+ */
+export async function propagateRipple(db, vector, manualPriority) {
+    const result = await db.execute({
+        sql: `SELECT id, priority, vector_distance_cos(embedding, ?) as distance FROM memories ORDER BY distance ASC LIMIT 5`,
+        args: [vector.buffer],
+    })
+    for (const row of result.rows) {
+        const similarity = 1 - row.distance
+        const resonantPriority = Math.round(manualPriority * similarity)
+        if (resonantPriority > row.priority) {
+            await db.execute({ sql: `UPDATE memories SET priority = ? WHERE id = ?`, args: [resonantPriority, row.id] })
+        }
+    }
+}
+
+/**
+ * Encontra o vizinho mais próximo para o Semantic Magnet.
+ */
+export async function findClosestNeighbor(db, vector) {
+    const result = await db.execute({
+        sql: `SELECT id, path, vector_distance_cos(embedding, ?) as distance FROM memories ORDER BY distance ASC LIMIT 1`,
+        args: [vector.buffer],
+    })
+    return result.rows[0] || null
+}

package/src/core/sip.js

@@ -0,0 +1,30 @@
+/**
+ * Self-Improvement Protocol (SIP) - Protocol Definition
+ * This document defines the core pillars of the RiLiGar self-improvement loop.
+ */
+export const SIP_PROTOCOL = `
+# RiLiGar Self-Improvement Protocol (SIP) v1.0
+
+The SIP transforms the memory system from a passive database into an active, self-correcting cognitive engine. Every agent using this MCP should adhere to the following three pillars:
+
+## 1. Pattern Mining (Refinamento de Padrões)
+- **Goal**: Identify common failure points and recurring logic patterns.
+- **Action**: When saving a new memory, always include the **Rationale** (the "Why").
+- **Loop**: Before taking a complex action, use \`search\` to find "Lessons Learned" and "Past Failures" related to the current context.
+
+## 2. Meta-Programming (Evolução de Skills)
+- **Goal**: Update internal instructions and code patterns based on discovered "State of the Art" (SOTA) solutions.
+- **Action**: If a specific implementation pattern proves superior (e.g., Elysia optimization), save it under \`Patterns.SOTA.*\` and update relevant local \`.agent/skills/\`.
+
+## 3. Self-Critique (Auditoria de Arquitetura)
+- **Goal**: Prevent technical debt and architectural drift.
+- **Action**: Periodically use \`inspect\` and \`search\` with filter \`path:Project.Architecture.*\` to identify redundancies or legacy constraints.
+- **Outcome**: Propose refactoring at the first sign of relational misalignment.
+
+---
+
+### Execution Protocol
+1. **CAPTURE**: Save rationale for every architectural decision.
+2. **REFLECT**: Search for patterns before starting new tasks.
+3. **EVOLVE**: Update skills and best practices paths based on successful outcomes.
+`.trim();

package/src/database/schema.js

@@ -0,0 +1,32 @@
+/**
+ * Esquema de banco de dados do RiLiGar Agents Memories.
+ * Utiliza extensões de vetor nativas do LibSQL (vector_distance_cos).
+ */
+
+export const SCHEMA_V1 = {
+  memories: `
+    CREATE TABLE IF NOT EXISTS memories (
+      id TEXT PRIMARY KEY DEFAULT (LOWER(HEX(RANDOMBLOB(5)))),
+      content TEXT NOT NULL,
+      path TEXT NOT NULL,
+      entities TEXT,
+      embedding F32_BLOB(384),
+      owner_id TEXT NOT NULL,
+      priority INTEGER DEFAULT 5,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+  `,
+  links: `
+    CREATE TABLE IF NOT EXISTS links (
+      source_id TEXT,
+      target_id TEXT,
+      relation_type TEXT,
+      PRIMARY KEY (source_id, target_id, relation_type)
+    );
+  `
+}
+
+export async function initializeSchema(db) {
+  await db.execute(SCHEMA_V1.memories)
+  await db.execute(SCHEMA_V1.links)
+}

package/src/index.js

@@ -1,344 +1,7 @@
-import { createClient } from '@libsql/client'
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
-import { pipeline } from '@huggingface/transformers'
-import express from 'express'
-import cors from 'cors'
-import fs from 'fs'
-import path from 'path'
-import crypto from 'crypto'
+// Main Export File for @riligar/agents-memories SDK
 
-// ==========================================
-// 1. DATABASE & SETUP (Relational Knowledge Graph)
-// ==========================================
-const db = createClient({ url: 'file:data/memories.db' })
-const DATA_DIR = 'data'
-const IDENTITY_JSON_PATH = path.join(DATA_DIR, 'identity.json')
-
-if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR)
-
-function getSystemIdentity() {
-    if (fs.existsSync(IDENTITY_JSON_PATH)) {
-        const data = JSON.parse(fs.readFileSync(IDENTITY_JSON_PATH, 'utf8'))
-        return data.owner_id
-    }
-
-    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519', {
-        publicKeyEncoding: { type: 'spki', format: 'pem' },
-        privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
-    })
-
-    const ownerId = crypto.createHash('sha256').update(publicKey).digest('hex').substring(0, 10)
-
-    fs.writeFileSync(IDENTITY_JSON_PATH, JSON.stringify({
-        owner_id: ownerId,
-        public_key: publicKey,
-        private_key: privateKey
-    }, null, 2), 'utf8')
-
-    console.error(`Generated new cryptographic identity: ${ownerId}`)
-    return ownerId
-}
-
-const SYSTEM_OWNER_ID = getSystemIdentity()
-console.error(`System Identity initialized: ${SYSTEM_OWNER_ID}`)
-
-await db.execute(`
-  CREATE TABLE IF NOT EXISTS memories (
-    id TEXT PRIMARY KEY DEFAULT (LOWER(HEX(RANDOMBLOB(5)))),
-    content TEXT NOT NULL,
-    path TEXT NOT NULL,
-    entities TEXT,
-    embedding F32_BLOB(384),
-    owner_id TEXT NOT NULL,
-    priority INTEGER DEFAULT 5,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-  );
-`)
-
-await db.execute(`
-  CREATE TABLE IF NOT EXISTS links (
-    source_id TEXT,
-    target_id TEXT,
-    relation_type TEXT,
-    PRIMARY KEY (source_id, target_id, relation_type)
-  );
-`)
-
-let extractor = null
-async function getEmbedding(text) {
-    if (!extractor) {
-        extractor = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2')
-    }
-    const output = await extractor(text, { pooling: 'mean', normalize: true })
-    return new Float32Array(output.data)
-}
-
-// ==========================================
-// 2. COGNITIVE LOGIC (Inference, Ripple & Graph)
-// ==========================================
-
-async function inferPriority(vector) {
-    const result = await db.execute({
-        sql: `SELECT priority, vector_distance_cos(embedding, ?) as distance FROM memories ORDER BY distance ASC LIMIT 5`,
-        args: [vector.buffer],
-    })
-    if (result.rows.length === 0) return 5
-    let weightedSum = 0,
-        totalWeight = 0
-    for (const row of result.rows) {
-        const similarity = 1 - row.distance
-        const weight = Math.pow(similarity, 2)
-        weightedSum += row.priority * weight
-        totalWeight += weight
-    }
-    return totalWeight > 0 ? Math.round(weightedSum / totalWeight) : 5
-}
-
-async function propagateRipple(vector, manualPriority) {
-    const result = await db.execute({
-        sql: `SELECT id, priority, vector_distance_cos(embedding, ?) as distance FROM memories ORDER BY distance ASC LIMIT 5`,
-        args: [vector.buffer],
-    })
-    for (const row of result.rows) {
-        const similarity = 1 - row.distance
-        const resonantPriority = Math.round(manualPriority * similarity)
-        if (resonantPriority > row.priority) {
-            await db.execute({ sql: `UPDATE memories SET priority = ? WHERE id = ?`, args: [resonantPriority, row.id] })
-        }
-    }
-}
-
-async function findClosestNeighbor(vector) {
-    const result = await db.execute({
-        sql: `SELECT id, path, vector_distance_cos(embedding, ?) as distance FROM memories ORDER BY distance ASC LIMIT 1`,
-        args: [vector.buffer],
-    })
-    return result.rows[0] || null
-}
-
-// ==========================================
-// 3. MCP SERVER FACTORY
-// ==========================================
-
-function createMcpServer() {
-    const server = new Server({ name: 'RiLiGar Agents Memories', version: '4.0.0' }, { capabilities: { tools: {} } })
-
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-        return {
-            tools: [
-                {
-                    name: 'save',
-                    description: 'Saves info with Resonance and Auto-Bridging (Semantic Magnet).',
-                    inputSchema: {
-                        type: 'object',
-                        properties: {
-                            content: {
-                                oneOf: [{ type: 'string' }, { type: 'array', items: { anyOf: [{ type: 'string' }, { type: 'object', properties: { content: { type: 'string' }, path: { type: 'string' }, owner_id: { type: 'string' }, priority: { type: 'integer' } }, required: ['content'] }] } }],
-                            },
-                            path: { type: 'string' },
-                            owner_id: { type: 'string' },
-                            priority: { type: 'integer' },
-                        },
-                        required: ['content'],
-                    },
-                },
-                {
-                    name: 'bridge',
-                    description: 'Manually connects two memory paths.',
-                    inputSchema: {
-                        type: 'object',
-                        properties: {
-                            source_path: { type: 'string' },
-                            target_path: { type: 'string' },
-                            relation: { type: 'string', default: 'related_to' },
-                        },
-                        required: ['source_path', 'target_path'],
-                    },
-                },
-                {
-                    name: 'search',
-                    description: 'Semantic search with Relational Awareness.',
-                    inputSchema: {
-                        type: 'object',
-                        properties: {
-                            query: { type: 'string' },
-                            path_filter: { type: 'string' },
-                        },
-                        required: ['query'],
-                    },
-                },
-                {
-                    name: 'inspect',
-                    description: 'Visualizes the Knowledge Graph in Mermaid.js syntax.',
-                    inputSchema: { type: 'object', properties: {} },
-                },
-                {
-                    name: 'list',
-                    description: 'Lists all memory paths.',
-                    inputSchema: { type: 'object', properties: {} },
-                },
-            ],
-        }
-    })
-
-    server.setRequestHandler(CallToolRequestSchema, async request => {
-        const { name, arguments: args } = request.params
-
-        try {
-            if (name === 'save') {
-                const results = []
-                const rawContent = args.content
-                const defaultPath = args.path || 'General'
-                const memoriesToSave = Array.isArray(rawContent) ? rawContent.map(m => (typeof m === 'string' ? { content: m } : m)) : [{ content: rawContent, path: args.path, owner_id: args.owner_id, priority: args.priority }]
-
-                for (const mem of memoriesToSave) {
-                    if (!mem.content) continue
-                    const vector = await getEmbedding(mem.content)
-                    const path = mem.path || defaultPath
-
-                    const neighbor = await findClosestNeighbor(vector)
-                    const isManualPriority = typeof mem.priority === 'number'
-                    const finalPriority = isManualPriority ? mem.priority : await inferPriority(vector)
-
-                    const insertRes = await db.execute({
-                        sql: `INSERT INTO memories (content, path, embedding, owner_id, priority) VALUES (?, ?, ?, ?, ?) RETURNING id`,
-                        args: [mem.content, path, vector.buffer, mem.owner_id || args.owner_id || SYSTEM_OWNER_ID, finalPriority],
-                    })
-                    const newId = insertRes.rows[0].id
-
-                    if (neighbor && 1 - neighbor.distance > 0.9) {
-                        await db.execute({
-                            sql: `INSERT OR IGNORE INTO links (source_id, target_id, relation_type) VALUES (?, ?, ?)`,
-                            args: [newId, neighbor.id, 'similar_to'],
-                        })
-                    }
-
-                    if (isManualPriority) await propagateRipple(vector, finalPriority)
-                    results.push(path)
-                }
-                return { content: [{ type: 'text', text: `Saved ${results.length} memories. Semantic Magnet applied.` }] }
-            }
-
-            if (name === 'bridge') {
-                const src = await db.execute({ sql: `SELECT id FROM memories WHERE path = ? LIMIT 1`, args: [args.source_path] })
-                const tgt = await db.execute({ sql: `SELECT id FROM memories WHERE path = ? LIMIT 1`, args: [args.target_path] })
-                if (!src.rows[0] || !tgt.rows[0]) throw new Error('Path(s) not found.')
-
-                await db.execute({
-                    sql: `INSERT OR IGNORE INTO links (source_id, target_id, relation_type) VALUES (?, ?, ?)`,
-                    args: [src.rows[0].id, tgt.rows[0].id, args.relation || 'related_to'],
-                })
-                return { content: [{ type: 'text', text: `Bridge created: [${args.source_path}] --(${args.relation})--> [${args.target_path}]` }] }
-            }
-
-            if (name === 'search') {
-                const vector = await getEmbedding(args.query)
-                let sql = `SELECT id, content, path, priority, created_at, vector_distance_cos(embedding, ?) as distance FROM memories`
-                const queryArgs = [vector.buffer],
-                    filters = []
-                if (args.path_filter) {
-                    filters.push(`path LIKE ?`)
-                    queryArgs.push(args.path_filter)
-                }
-                if (filters.length > 0) sql += ` WHERE ` + filters.join(' AND ')
-
-                const result = await db.execute({ sql, args: queryArgs })
-                const rows = result.rows
-                    .map(r => ({ ...r, score: (1 - r.distance) * 0.6 + (1 / (1 + (new Date() - new Date(r.created_at)) / 86400000)) * 0.4 }))
-                    .sort((a, b) => b.score - a.score)
-                    .slice(0, 5)
-
-                const formattedResults = []
-                for (const r of rows) {
-                    const links = await db.execute({
-                        sql: `SELECT m.path, l.relation_type FROM links l JOIN memories m ON l.target_id = m.id WHERE l.source_id = ?`,
-                        args: [r.id],
-                    })
-                    const linkText = links.rows.length > 0 ? `\n🔗 Related: ${links.rows.map(l => `${l.path} (${l.relation_type})`).join(', ')}` : ''
-                    formattedResults.push(`[${r.path} | P:${r.priority}] ${r.content}${linkText}`)
-                }
-                return { content: [{ type: 'text', text: formattedResults.join('\n\n') || 'No results.' }] }
-            }
-
-            if (name === 'inspect') {
-                const result = await db.execute(`
-                    SELECT m1.path as src, m2.path as tgt, l.relation_type as rel 
-                    FROM links l 
-                    JOIN memories m1 ON l.source_id = m1.id 
-                    JOIN memories m2 ON l.target_id = m2.id
-                `)
-                let mermaid = 'graph TD\n'
-                result.rows.forEach(r => {
-                    mermaid += `    ${r.src.replace(/\./g, '_')}["${r.src}"] -- "${r.rel}" --> ${r.tgt.replace(/\./g, '_')}["${r.tgt}"]\n`
-                })
-                return { content: [{ type: 'text', text: `### Knowledge Graph\n\n\`\`\`mermaid\n${mermaid}\`\`\`` }] }
-            }
-
-            if (name === 'list') {
-                const result = await db.execute(`SELECT DISTINCT path FROM memories ORDER BY path`)
-                return { content: [{ type: 'text', text: result.rows.map(r => `- ${r.path}`).join('\n') || 'Empty.' }] }
-            }
-
-            throw new Error('Unknown tool.')
-        } catch (error) {
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true }
-        }
-    })
-
-    return server
-}
-
-// ==========================================
-// 4. CONNECTION HANDLING (STDIO + HTTP)
-// ==========================================
-
-// 4.1. STDIO Connection
-const stdioServer = createMcpServer()
-const stdioTransport = new StdioServerTransport()
-stdioServer.connect(stdioTransport).catch(err => console.error('STDIO Error:', err))
-console.error('RiLiGar Agents Memories running via STDIO.')
-
-// 4.2. Express Server with SDK SSE Transport
-const app = express()
-app.use(cors())
-// Note: We do NOT use express.json() because SSEServerTransport handles body parsing manually via getRawBody.
-
-const sseSessions = new Map()
-
-app.get('/health', (req, res) => {
-    res.status(200).send('OK')
-})
-
-app.get('/sse', async (req, res) => {
-    const transport = new SSEServerTransport('/messages', res)
-    const sessionServer = createMcpServer()
-    await sessionServer.connect(transport)
-
-    const sessionId = transport.sessionId
-    sseSessions.set(sessionId, transport)
-    console.error(`SSE session started: ${sessionId}`)
-
-    res.on('close', () => {
-        console.error(`SSE session closed: ${sessionId}`)
-        sseSessions.delete(sessionId)
-    })
-})
-
-app.post('/messages', async (req, res) => {
-    const sessionId = req.query.sessionId
-    const transport = sseSessions.get(sessionId)
-
-    if (!transport) {
-        return res.status(404).send('Session not found')
-    }
-
-    await transport.handlePostMessage(req, res)
-})
-
-const PORT = 3000
-app.listen(PORT, () => {
-    console.error(`RiLiGar Agents Memories (Express) running at http://localhost:${PORT}`)
-})
+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'

package/src/sdk/memory-system.js

@@ -0,0 +1,143 @@
+import crypto from 'crypto'
+import { getEmbedding, inferPriority, propagateRipple, findClosestNeighbor } from '../core/logic.js'
+import { initializeSchema } from '../database/schema.js'
+
+/**
+ * MemorySystem: A interface programática do RiLiGar Agents Memories.
+ * Desacoplada de transporte (SSE/Stdio) e orquestração.
+ */
+export class MemorySystem {
+  constructor(db, ownerId = null) {
+    this.db = db
+    this.ownerId = ownerId
+  }
+
+  /**
+   * Inicializa o sistema (Schema).
+   */
+  async init() {
+    await initializeSchema(this.db)
+  }
+
+  /**
+   * Salva uma memória com Ressonância e Magnetismo Semântico.
+   */
+  async save(args) {
+    const rawContent = args.content
+    const defaultPath = args.path || 'General'
+    const memoriesToSave = Array.isArray(rawContent) 
+      ? rawContent.map(m => (typeof m === 'string' ? { content: m } : m)) 
+      : [{ content: rawContent, path: args.path, owner_id: args.owner_id, priority: args.priority }]
+
+    const results = []
+    for (const mem of memoriesToSave) {
+      if (!mem.content) continue
+      const vector = await getEmbedding(mem.content)
+      const path = mem.path || defaultPath
+      const ownerId = mem.owner_id || args.owner_id || this.ownerId
+
+      const neighbor = await findClosestNeighbor(this.db, vector)
+      const isManualPriority = typeof mem.priority === 'number'
+      const finalPriority = isManualPriority ? mem.priority : await inferPriority(this.db, vector)
+
+      const insertRes = await this.db.execute({
+        sql: `INSERT INTO memories (content, path, embedding, owner_id, priority) VALUES (?, ?, ?, ?, ?) RETURNING id`,
+        args: [mem.content, path, vector.buffer, ownerId, finalPriority],
+      })
+      const newId = insertRes.rows[0].id
+
+      // Semantic Magnet: Auto-bridge near-identical facts
+      if (neighbor && 1 - neighbor.distance > 0.9) {
+        await this.db.execute({
+          sql: `INSERT OR IGNORE INTO links (source_id, target_id, relation_type) VALUES (?, ?, ?)`,
+          args: [newId, neighbor.id, 'similar_to'],
+        })
+      }
+
+      if (isManualPriority) await propagateRipple(this.db, vector, finalPriority)
+      results.push(path)
+    }
+    
+    return { results, count: results.length }
+  }
+
+  /**
+   * Busca semântica relacional.
+   */
+  async search(args) {
+    const vector = await getEmbedding(args.query)
+    let sql = `SELECT id, content, path, priority, created_at, vector_distance_cos(embedding, ?) as distance FROM memories`
+    const queryArgs = [vector.buffer], filters = []
+    
+    if (args.path_filter) {
+      filters.push(`path LIKE ?`)
+      queryArgs.push(args.path_filter)
+    }
+    
+    if (filters.length > 0) sql += ` WHERE ` + filters.join(' AND ')
+
+    const result = await this.db.execute({ sql, args: queryArgs })
+    const rows = result.rows
+      .map(r => ({ 
+        ...r, 
+        score: (1 - r.distance) * 0.6 + (1 / (1 + (new Date() - new Date(r.created_at)) / 86400000)) * 0.4 
+      }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 5)
+
+    const formattedResults = []
+    for (const r of rows) {
+      const links = await this.db.execute({
+        sql: `SELECT m.path, l.relation_type FROM links l JOIN memories m ON l.target_id = m.id WHERE l.source_id = ?`,
+        args: [r.id],
+      })
+      formattedResults.push({
+        ...r,
+        links: links.rows
+      })
+    }
+    return formattedResults
+  }
+
+  /**
+   * Cria uma ponte manual entre dois caminhos.
+   */
+  async bridge(args) {
+    const src = await this.db.execute({ sql: `SELECT id FROM memories WHERE path = ? LIMIT 1`, args: [args.source_path] })
+    const tgt = await this.db.execute({ sql: `SELECT id FROM memories WHERE path = ? LIMIT 1`, args: [args.target_path] })
+    
+    if (!src.rows[0] || !tgt.rows[0]) throw new Error('Path(s) not found.')
+
+    await this.db.execute({
+      sql: `INSERT OR IGNORE INTO links (source_id, target_id, relation_type) VALUES (?, ?, ?)`,
+      args: [src.rows[0].id, tgt.rows[0].id, args.relation || 'related_to'],
+    })
+    
+    return true
+  }
+
+  /**
+   * Gera o Knowledge Graph em formato Mermaid.
+   */
+  async inspect() {
+    const result = await this.db.execute(`
+      SELECT m1.path as src, m2.path as tgt, l.relation_type as rel 
+      FROM links l 
+      JOIN memories m1 ON l.source_id = m1.id 
+      JOIN memories m2 ON l.target_id = m2.id
+    `)
+    let mermaid = 'graph TD\n'
+    result.rows.forEach(r => {
+      mermaid += `    ${r.src.replace(/\./g, '_')}["${r.src}"] -- "${r.rel}" --> ${r.tgt.replace(/\./g, '_')}["${r.tgt}"]\n`
+    })
+    return mermaid
+  }
+
+  /**
+   * Lista caminhos únicos.
+   */
+  async list() {
+    const result = await this.db.execute(`SELECT DISTINCT path FROM memories ORDER BY path`)
+    return result.rows.map(r => r.path)
+  }
+}

package/src/server/index.js

@@ -0,0 +1,56 @@
+import { createClient } from '@libsql/client'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'
+import express from 'express'
+import cors from 'cors'
+import path from 'path'
+
+import { MemorySystem, getSystemIdentity, createMcpServer } from '../index.js'
+
+// 1. SETUP
+const DATA_DIR = 'data'
+const SYSTEM_OWNER_ID = getSystemIdentity(DATA_DIR)
+const db = createClient({ url: `file:${path.join(DATA_DIR, 'memories.db')}` })
+
+const memorySystem = new MemorySystem(db, SYSTEM_OWNER_ID)
+await memorySystem.init()
+
+console.error(`RiLiGar Agents Memories initialized for Owner: ${SYSTEM_OWNER_ID}`)
+
+// 2. TRANSPORTS
+// 2.1. STDIO
+const mcpServer = createMcpServer(memorySystem)
+const stdioTransport = new StdioServerTransport()
+mcpServer.connect(stdioTransport).catch(err => console.error('STDIO Error:', err))
+
+// 2.2. SSE (Express)
+const app = express()
+app.use(cors())
+const sseSessions = new Map()
+
+app.get('/sse', async (req, res) => {
+    const transport = new SSEServerTransport('/messages', res)
+    const sessionServer = createMcpServer(memorySystem)
+    await sessionServer.connect(transport)
+
+    const sessionId = transport.sessionId
+    sseSessions.set(sessionId, transport)
+    console.error(`SSE session started: ${sessionId}`)
+
+    res.on('close', () => {
+        sseSessions.delete(sessionId)
+        console.error(`SSE session closed: ${sessionId}`)
+    })
+})
+
+app.post('/messages', async (req, res) => {
+    const sessionId = req.query.sessionId
+    const transport = sseSessions.get(sessionId)
+    if (!transport) return res.status(404).send('Session not found')
+    await transport.handlePostMessage(req, res)
+})
+
+const PORT = process.env.PORT || 3000
+app.listen(PORT, () => {
+    console.error(`RiLiGar Agents Memories Standalone running at http://localhost:${PORT}`)
+})

package/src/server/mcp-server.js

@@ -0,0 +1,158 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { 
+    CallToolRequestSchema, 
+    ListToolsRequestSchema, 
+    ListResourcesRequestSchema, 
+    ReadResourceRequestSchema 
+} from '@modelcontextprotocol/sdk/types.js'
+import { SIP_PROTOCOL } from '../core/sip.js'
+
+/**
+ * Factory para criar o servidor MCP usando o SDK do RiLiGar.
+ */
+export function createMcpServer(memorySystem) {
+    const server = new Server(
+        { name: 'RiLiGar Agents Memories', version: '4.2.0' }, 
+        { capabilities: { tools: {}, resources: {} } }
+    )
+
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [
+                {
+                    name: 'save',
+                    description: 'Saves info with Resonance and Auto-Bridging. SIP Note: Capture the Rationale (the "Why") to enable Pattern Mining.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            content: {
+                                oneOf: [
+                                    { type: 'string' }, 
+                                    { type: 'array', items: { anyOf: [
+                                        { type: 'string' }, 
+                                        { type: 'object', properties: { 
+                                            content: { type: 'string' }, 
+                                            path: { type: 'string' }, 
+                                            owner_id: { type: 'string' }, 
+                                            priority: { type: 'integer' } 
+                                        }, required: ['content'] }
+                                    ] } }
+                                ],
+                            },
+                            path: { type: 'string' },
+                            owner_id: { type: 'string' },
+                            priority: { type: 'integer' },
+                        },
+                        required: ['content'],
+                    },
+                },
+                {
+                    name: 'bridge',
+                    description: 'Manually connects two memory paths.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            source_path: { type: 'string' },
+                            target_path: { type: 'string' },
+                            relation: { type: 'string', default: 'related_to' },
+                        },
+                        required: ['source_path', 'target_path'],
+                    },
+                },
+                {
+                    name: 'search',
+                    description: 'Semantic search with Relational Awareness. Use for Pattern Mining and Error Avoidance (SIP).',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: { type: 'string' },
+                            path_filter: { type: 'string' },
+                        },
+                        required: ['query'],
+                    },
+                },
+                {
+                    name: 'inspect',
+                    description: 'Visualizes the Knowledge Graph in Mermaid.js syntax. Use for Architecture Audit (SIP).',
+                    inputSchema: { type: 'object', properties: {} },
+                },
+                {
+                    name: 'list',
+                    description: 'Lists all memory paths.',
+                    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
+}

package/src/test.js

@@ -10,7 +10,7 @@ async function runTest() {
 
     const transport = new StdioClientTransport({
         command: process.platform === 'win32' ? 'bun.exe' : (process.env.HOME + '/.bun/bin/bun'),
-        args: ['src/index.js']
+        args: ['src/server/index.js']
     })
 
     const client = new Client(

package/src/test_identity.js

@@ -16,7 +16,7 @@ async function runIdentityTest() {
 
     const transport = new StdioClientTransport({
         command: (process.env.HOME + '/.bun/bin/bun'),
-        args: ['src/index.js']
+        args: ['src/server/index.js']
     })
 
     const client = new Client(