@riligar/agents-memories 1.1.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.1.0",
-    "description": "RiLiGar Agents Memories - A persistent memories system for AI agents (Modular SDK).",
+    "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",

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/server/mcp-server.js

@@ -1,13 +1,19 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.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.1.0' }, 
-        { capabilities: { tools: {} } }
+        { name: 'RiLiGar Agents Memories', version: '4.2.0' }, 
+        { capabilities: { tools: {}, resources: {} } }
     )
 
     server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -15,7 +21,7 @@ export function createMcpServer(memorySystem) {
             tools: [
                 {
                     name: 'save',
-                    description: 'Saves info with Resonance and Auto-Bridging (Semantic Magnet).',
+                    description: 'Saves info with Resonance and Auto-Bridging. SIP Note: Capture the Rationale (the "Why") to enable Pattern Mining.',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -55,7 +61,7 @@ export function createMcpServer(memorySystem) {
                 },
                 {
                     name: 'search',
-                    description: 'Semantic search with Relational Awareness.',
+                    description: 'Semantic search with Relational Awareness. Use for Pattern Mining and Error Avoidance (SIP).',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -67,7 +73,7 @@ export function createMcpServer(memorySystem) {
                 },
                 {
                     name: 'inspect',
-                    description: 'Visualizes the Knowledge Graph in Mermaid.js syntax.',
+                    description: 'Visualizes the Knowledge Graph in Mermaid.js syntax. Use for Architecture Audit (SIP).',
                     inputSchema: { type: 'object', properties: {} },
                 },
                 {
@@ -79,6 +85,34 @@ export function createMcpServer(memorySystem) {
         }
     })
 
+    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