@lantanios/agentic-server 0.2.0 → 0.2.2

package/README.md

@@ -1,14 +1,17 @@
 # @lantanios/agentic-server
 
-Real-time Socket.IO server combining memory, audio, and event communication for AI agents.
+Real-time Socket.IO server combining memory, audio, event communication, context assembly, and cache synchronization for AI agents.
 
 ## Features
 
-- 🔌 **Socket.IO namespaces** — Separate channels for memory, audio, events
-- 🧠 **Memory namespace** — CRUD + vector search via WebSocket
-- 🎙️ **Audio namespace** — Real-time STT/TTS streaming
-- 📡 **Events namespace** — Pub/sub, broadcast, direct messaging between agents
-- 🔄 **Priority providers** — Local-first audio with cloud fallback
+- **Socket.IO namespaces** — Separate channels for memory, audio, events, context, and sync
+- **Memory namespace** — CRUD + vector search via WebSocket
+- **Audio namespace** — Real-time STT/TTS streaming
+- **Events namespace** — Pub/sub, broadcast, direct messaging between agents
+- **Context namespace** — Context assembly, hybrid recall, goal tracking, and conversation summarization
+- **Sync namespace** — Redis-backed cache synchronization for offline-first memory access
+- **Priority providers** — Local-first audio with cloud fallback
+- **Redis integration** — Pub/sub and caching layer for sync operations
 
 ## Installation
 
@@ -28,6 +31,9 @@ CORS_ORIGINS=http://localhost:3000,http://localhost:5173
 # MongoDB (required)
 MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/Agentic
 
+# Redis (required for /sync namespace, optional otherwise)
+REDIS_URL=redis://localhost:6379
+
 # OpenAI (required for embeddings, optional for TTS)
 OPENAI_API_KEY=sk-...
 
@@ -70,6 +76,16 @@ const audio = io('http://localhost:3847/audio', {
 const events = io('http://localhost:3847/events', {
   auth: { agentId: 'pip' }
 });
+
+// Connect to context namespace
+const context = io('http://localhost:3847/context', {
+  auth: { agentId: 'pip' }
+});
+
+// Connect to sync namespace
+const sync = io('http://localhost:3847/sync', {
+  auth: { agentId: 'pip' }
+});
 ```
 
 ## Socket.IO Namespaces
@@ -302,6 +318,232 @@ events.emit('agents:list', (response) => {
 });
 ```
 
+### `/context` — Context Assembly & Goals
+
+Handles context window management, hybrid recall across memories and summaries, conversation compression, and goal tracking. All operations require `agentId` in auth.
+
+#### Search Memories (Atlas Vector Search)
+
+```typescript
+context.emit('search:memories', {
+  query: 'user preferences for the dashboard',
+  limit: 10,
+  minScore: 0.7,
+}, (response) => {
+  if (response.success) {
+    response.results.forEach(r => {
+      console.log(`${r.score.toFixed(2)}: ${r.content}`);
+    });
+  }
+});
+```
+
+#### Search Summaries (Atlas Vector Search)
+
+```typescript
+context.emit('search:summaries', {
+  query: 'previous discussions about deployment',
+  limit: 5,
+  minScore: 0.6,
+}, (response) => {
+  if (response.success) {
+    response.results.forEach(r => {
+      console.log(`${r.score.toFixed(2)}: ${r.summary}`);
+    });
+  }
+});
+```
+
+#### Hybrid Recall
+
+Combines important memories, recent memories, semantic search results, and summaries into a single ranked context payload.
+
+```typescript
+context.emit('recall', {
+  query: 'What has the user said about the API redesign?',
+  sessionId: 'session-abc-123',
+  limit: 30,
+}, (response) => {
+  if (response.success) {
+    console.log('Important:', response.breakdown.important);
+    console.log('Recent:', response.breakdown.recent);
+    console.log('Semantic:', response.breakdown.semantic);
+    console.log('Summaries:', response.breakdown.summaries);
+    console.log('Combined memories:', response.memories);
+  }
+});
+```
+
+#### Compress & Store Summary
+
+Stores a conversation summary along with extracted facts for future recall.
+
+```typescript
+context.emit('compress:store', {
+  sessionId: 'session-abc-123',
+  summary: 'User discussed API redesign. Decided on REST over GraphQL. Key concern: backwards compatibility.',
+  facts: [
+    { content: 'User chose REST over GraphQL for API redesign', type: 'decision', importance: 5 },
+    { content: 'Backwards compatibility is a key concern', type: 'fact', importance: 4 },
+  ],
+  tokensSaved: 1200,
+}, (response) => {
+  if (response.success) {
+    console.log('Summary stored:', response.summaryId);
+    console.log('Facts created:', response.factsCreated);
+  }
+});
+```
+
+#### Get Context State
+
+Retrieve the current context window state for a session (tokens used, model, window size).
+
+```typescript
+context.emit('state:get', {
+  sessionId: 'session-abc-123',
+}, (response) => {
+  if (response.success) {
+    console.log('Tokens used:', response.state.tokensUsed);
+    console.log('Context window:', response.state.contextWindow);
+    console.log('Model:', response.state.model);
+  }
+});
+```
+
+#### Update Context State
+
+```typescript
+context.emit('state:update', {
+  sessionId: 'session-abc-123',
+  tokensUsed: 14500,
+  model: 'claude-opus-4-6',
+  contextWindow: 200000,
+}, (response) => {
+  if (response.success) {
+    console.log('State updated');
+  }
+});
+```
+
+#### Get Goals
+
+Retrieve active, blocked, or filtered goals for the agent.
+
+```typescript
+context.emit('goals:get', {
+  status: 'active',       // optional: 'active' | 'blocked' | 'completed' | 'abandoned'
+  priority: 'high',       // optional: 'low' | 'medium' | 'high' | 'critical'
+  limit: 20,
+}, (response) => {
+  if (response.success) {
+    response.goals.forEach(g => {
+      console.log(`[${g.priority}] ${g.description} — ${g.status}`);
+    });
+  }
+});
+```
+
+#### Update Goal
+
+```typescript
+context.emit('goals:update', {
+  goalId: 'goal-xyz-789',
+  status: 'completed',
+  description: 'Finish API redesign proposal',  // optional
+  priority: 'high',                               // optional
+}, (response) => {
+  if (response.success) {
+    console.log('Goal updated:', response.goal);
+  }
+});
+```
+
+#### Create Goal
+
+```typescript
+context.emit('goals:create', {
+  description: 'Implement Redis caching layer for sync namespace',
+  priority: 'high',
+  status: 'active',
+  metadata: {
+    project: 'agentic-server',
+    tags: ['infrastructure', 'performance'],
+  },
+}, (response) => {
+  if (response.success) {
+    console.log('Goal created:', response.goal.id);
+  }
+});
+```
+
+### `/sync` — Cache Synchronization
+
+Enables offline-first memory access with Redis-backed cache synchronization. Agents can pull recently updated memories, push locally-created ones, and check sync state. Requires Redis (`REDIS_URL` env var).
+
+#### Pull Updates
+
+Fetch memories that have been updated since a given timestamp, for local cache hydration.
+
+```typescript
+sync.emit('sync:pull', {
+  since: '2026-02-05T00:00:00.000Z',  // ISO timestamp
+  limit: 100,
+}, (response) => {
+  if (response.success) {
+    console.log(`Pulled ${response.memories.length} updated memories`);
+    console.log('Server timestamp:', response.serverTimestamp);
+    // Store response.serverTimestamp for next pull
+  }
+});
+```
+
+#### Push Local Memories
+
+Push memories created locally (while offline or in a local cache) up to MongoDB.
+
+```typescript
+sync.emit('sync:push', {
+  memories: [
+    {
+      localId: 'local-001',
+      type: 'fact',
+      content: 'User mentioned they use VS Code',
+      metadata: { importance: 3, tags: ['tools'] },
+      createdAt: '2026-02-05T12:30:00.000Z',
+    },
+    {
+      localId: 'local-002',
+      type: 'conversation',
+      content: 'Discussed project timelines for Q2',
+      metadata: { importance: 4, tags: ['planning'] },
+      createdAt: '2026-02-05T12:35:00.000Z',
+    },
+  ],
+}, (response) => {
+  if (response.success) {
+    console.log(`Pushed ${response.created} memories`);
+    // response.mapping: { 'local-001': 'mongo-id-abc', 'local-002': 'mongo-id-def' }
+    console.log('ID mapping:', response.mapping);
+  }
+});
+```
+
+#### Sync Status
+
+Check the current sync state for the agent, including last sync time and pending counts.
+
+```typescript
+sync.emit('sync:status', (response) => {
+  if (response.success) {
+    console.log('Last pull:', response.status.lastPull);
+    console.log('Last push:', response.status.lastPush);
+    console.log('Pending pushes:', response.status.pendingPushes);
+    console.log('Server behind by:', response.status.serverDelta, 'records');
+  }
+});
+```
+
 ## REST Endpoints
 
 | Method | Path | Description |
@@ -321,13 +563,20 @@ curl http://localhost:3847/providers
 
 ```
 Client (Browser/Node)
-    │
-    ├── Socket.IO ─────► /memory  ────► MongoDB + OpenAI Embeddings
-    │
-    ├── Socket.IO ─────► /audio   ────► Local Whisper/Piper
-    │                                   └──► Deepgram/OpenAI (fallback)
-    │
-    └── Socket.IO ─────► /events  ────► Pub/Sub (in-memory)
+    |
+    |--- Socket.IO ------> /memory  -------> MongoDB + OpenAI Embeddings
+    |
+    |--- Socket.IO ------> /audio   -------> Local Whisper/Piper
+    |                                         +---> Deepgram/OpenAI (fallback)
+    |
+    |--- Socket.IO ------> /events  -------> Pub/Sub (in-memory)
+    |
+    |--- Socket.IO ------> /context -------> MongoDB Atlas Vector Search
+    |                                         +---> Goals collection
+    |                                         +---> Summaries collection
+    |
+    +--- Socket.IO ------> /sync    -------> Redis (cache + pub/sub)
+                                              +---> MongoDB (persistence)
 ```
 
 ## Example: Full Agent Connection
@@ -339,6 +588,8 @@ class AgentClient {
   private memory;
   private audio;
   private events;
+  private context;
+  private sync;
 
   constructor(serverUrl: string, agentId: string) {
     const auth = { agentId };
@@ -346,6 +597,8 @@ class AgentClient {
     this.memory = io(`${serverUrl}/memory`, { auth });
     this.audio = io(`${serverUrl}/audio`, { auth });
     this.events = io(`${serverUrl}/events`, { auth });
+    this.context = io(`${serverUrl}/context`, { auth });
+    this.sync = io(`${serverUrl}/sync`, { auth });
 
     // Subscribe to relevant channels
     this.events.emit('subscribe', 'system');
@@ -365,6 +618,36 @@ class AgentClient {
     });
   }
 
+  async recall(query: string, sessionId: string) {
+    return new Promise((resolve) => {
+      this.context.emit('recall', { query, sessionId, limit: 30 }, resolve);
+    });
+  }
+
+  async getGoals(status = 'active') {
+    return new Promise((resolve) => {
+      this.context.emit('goals:get', { status }, resolve);
+    });
+  }
+
+  async createGoal(description: string, priority = 'medium') {
+    return new Promise((resolve) => {
+      this.context.emit('goals:create', { description, priority, status: 'active' }, resolve);
+    });
+  }
+
+  async syncPull(since: string) {
+    return new Promise((resolve) => {
+      this.sync.emit('sync:pull', { since }, resolve);
+    });
+  }
+
+  async syncPush(memories: any[]) {
+    return new Promise((resolve) => {
+      this.sync.emit('sync:push', { memories }, resolve);
+    });
+  }
+
   async transcribe(audioBuffer: Buffer) {
     return new Promise((resolve) => {
       this.audio.emit('transcribe', { audio: audioBuffer }, resolve);
@@ -390,6 +673,10 @@ class AgentClient {
 const agent = new AgentClient('http://localhost:3847', 'pip');
 await agent.remember('User asked about weather', 'conversation', 2);
 const results = await agent.search('weather conversations');
+const context = await agent.recall('weather conversations', 'session-001');
+const goals = await agent.getGoals('active');
+await agent.createGoal('Investigate weather API options', 'high');
+await agent.syncPull('2026-02-05T00:00:00.000Z');
 ```
 
 ## License

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "@lantanios/agentic-server",
-  "version": "0.2.0",
-  "description": "Real-time server with Socket.IO for memory and audio streaming",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "keywords": [
-    "socket.io",
-    "realtime",
-    "audio",
-    "memory",
-    "ai"
-  ],
-  "author": "Lantanios",
-  "license": "UNLICENSED",
-  "publishConfig": {
-    "access": "restricted"
-  },
-  "dependencies": {
-    "cors": "^2.8.5",
-    "dotenv": "^16.0.0",
-    "express": "^4.18.0",
-    "mongoose": "^8.0.0",
-    "socket.io": "^4.7.0",
-    "@lantanios/agentic-memory": "0.3.0",
-    "@lantanios/agentic-audio": "0.1.1",
-    "@lantanios/agentic-redis": "0.1.0"
-  },
-  "devDependencies": {
-    "@types/cors": "^2.8.0",
-    "@types/express": "^4.17.0",
-    "@types/node": "^20.0.0",
-    "ts-node-dev": "^2.0.0",
-    "typescript": "^5.0.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "ts-node-dev --respawn src/index.ts",
-    "start": "node dist/index.js",
-    "lint": "eslint src --ext .ts"
-  }
-}
+{
+  "name": "@lantanios/agentic-server",
+  "version": "0.2.2",
+  "description": "Real-time server with Socket.IO for memory and audio streaming",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node-dev --respawn src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint src --ext .ts"
+  },
+  "keywords": [
+    "socket.io",
+    "realtime",
+    "audio",
+    "memory",
+    "ai"
+  ],
+  "author": "Lantanios",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "dependencies": {
+    "@lantanios/agentic-audio": "workspace:*",
+    "@lantanios/agentic-memory": "workspace:*",
+    "@lantanios/agentic-redis": "workspace:*",
+    "cors": "^2.8.5",
+    "dotenv": "^16.0.0",
+    "express": "^4.18.0",
+    "mongoose": "^8.0.0",
+    "socket.io": "^4.7.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.0",
+    "@types/express": "^4.17.0",
+    "@types/node": "^20.0.0",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.0.0"
+  }
+}