agentic-flow 1.9.0 → 1.9.2

package/agentic-flow/examples/federated-agentdb/README.md

@@ -1,494 +0,0 @@
-# Federated AgentDB - Secure Memory for Ephemeral Agents
-
-## Overview
-
-Federated AgentDB provides secure, distributed memory for short-lived (ephemeral) agents with:
-
-- **QUIC-based synchronization** (<50ms latency)
-- **Zero-trust security** (mTLS + JWT + AES-256)
-- **Tenant isolation** (multi-tenant SaaS ready)
-- **Automatic lifecycle** (spawn → execute → learn → destroy)
-- **Persistent memory** (memory survives agent destruction)
-
-## Key Features
-
-### 1. Ephemeral Agent Lifecycle
-
-Agents are short-lived (5 seconds to 15 minutes) but have access to persistent memory:
-
-```typescript
-const agent = await EphemeralAgent.spawn({
-  tenantId: 'acme-corp',
-  lifetime: 300, // 5 minutes
-  hubEndpoint: 'quic://hub.agentdb.io:4433'
-});
-
-const result = await agent.execute(async (db, context) => {
-  // Query past experiences
-  const memories = await agent.queryMemories('task description');
-
-  // Execute task
-  const output = processTask(memories);
-
-  // Store learning
-  await agent.storeEpisode({
-    task: 'task-name',
-    input: '...',
-    output: output,
-    reward: 0.95
-  });
-
-  return output;
-});
-// Agent auto-destroyed, memory persists
-```
-
-### 2. Multi-Region Synchronization
-
-Agents connect to regional hubs for low-latency access:
-
-```
-Edge (London) → EU Hub → Global Hub → US Hub → Edge (New York)
-   <10ms          ~50ms     ~100ms      ~50ms        <10ms
-```
-
-### 3. Tenant Isolation
-
-Each tenant has a completely isolated memory space:
-
-```typescript
-// Tenant A - Cannot access Tenant B's memories
-const agentA = await EphemeralAgent.spawn({
-  tenantId: 'acme-corp',
-  lifetime: 300
-});
-
-// Tenant B - Cannot access Tenant A's memories
-const agentB = await EphemeralAgent.spawn({
-  tenantId: 'globex-inc',
-  lifetime: 300
-});
-```
-
-### 4. Security Layers
-
-**4-Layer Zero-Trust Security:**
-
-1. **Transport Layer**: mTLS (mutual TLS) for all hub connections
-2. **Application Layer**: JWT tokens (5-minute expiry)
-3. **Data Layer**: AES-256 encryption at rest
-4. **Isolation Layer**: Tenant-based access control
-
-## Use Cases
-
-### Serverless Functions (AWS Lambda, Azure Functions)
-
-Perfect for Lambda functions (5-15 minute execution):
-
-```typescript
-// lambda.ts
-import { EphemeralAgent } from 'agentic-flow/federation';
-
-export async function handler(event) {
-  const agent = await EphemeralAgent.spawn({
-    tenantId: event.tenantId,
-    lifetime: 900, // 15 minutes (Lambda max)
-    hubEndpoint: process.env.HUB_ENDPOINT
-  });
-
-  return await agent.execute(async (db) => {
-    // Access memories from previous Lambda invocations
-    const memories = await agent.queryMemories(event.query);
-
-    // Process with context
-    const result = await processQuery(event.query, memories);
-
-    // Store for next invocation
-    await agent.storeEpisode({
-      task: event.query,
-      input: event.query,
-      output: result,
-      reward: 0.9
-    });
-
-    return result;
-  });
-}
-```
-
-**Benefits:**
-- Memory persists across cold starts
-- Learn from all past invocations
-- Low overhead (<50ms sync)
-
-### Edge Computing (Cloudflare Workers, Fastly)
-
-Ultra-low-latency edge functions (50ms-5s):
-
-```typescript
-// worker.ts
-export default {
-  async fetch(request, env) {
-    const region = request.cf?.colo; // Datacenter code
-
-    const agent = await EphemeralAgent.spawn({
-      tenantId: getTenantFromRequest(request),
-      lifetime: 30, // 30 seconds (quick edge execution)
-      hubEndpoint: getRegionalHub(region) // Connect to nearest hub
-    });
-
-    return await agent.execute(async (db) => {
-      // Fast regional memory access (<10ms)
-      const memories = await agent.queryMemories('user-request');
-
-      return processEdgeRequest(request, memories);
-    });
-  }
-};
-```
-
-**Benefits:**
-- Regional data residency (GDPR compliance)
-- <10ms memory access (local hub)
-- Global learning (eventual consistency)
-
-### Multi-Tenant SaaS
-
-Isolated memory per customer:
-
-```typescript
-app.post('/api/process', async (req, res) => {
-  const { tenantId, task } = req.body;
-
-  const agent = await EphemeralAgent.spawn({
-    tenantId, // All queries filtered by tenant
-    lifetime: 600, // 10 minutes
-    enableEncryption: true
-  });
-
-  const result = await agent.execute(async (db) => {
-    // Only access this tenant's memories
-    const memories = await agent.queryMemories(task);
-
-    return processTenantTask(task, memories);
-  });
-
-  res.json(result);
-});
-```
-
-**Benefits:**
-- Complete tenant isolation
-- Shared infrastructure (cost efficient)
-- Per-tenant learning
-- SOC2/HIPAA/GDPR compliant
-
-## Examples
-
-### 1. Serverless Lambda
-
-See [`serverless-lambda.ts`](./serverless-lambda.ts) for complete AWS Lambda integration.
-
-**Key Features:**
-- 15-minute lifetime (Lambda max)
-- Memory persists across cold starts
-- Multi-tenant support
-
-### 2. Edge Computing
-
-See [`edge-cloudflare-worker.ts`](./edge-cloudflare-worker.ts) for Cloudflare Workers integration.
-
-**Key Features:**
-- 30-second lifetime (quick edge execution)
-- Regional hubs for <10ms latency
-- Data residency compliance
-
-### 3. Multi-Tenant SaaS
-
-See [`multi-tenant-saas.ts`](./multi-tenant-saas.ts) for Express.js API server.
-
-**Key Features:**
-- Tenant isolation
-- Encrypted data at rest
-- Admin endpoints for stats
-
-## Architecture
-
-### Agent Lifecycle
-
-```
-1. SPAWN
-   ├─ Create JWT token (5-min expiry)
-   ├─ Connect to federation hub (QUIC)
-   ├─ Initialize local AgentDB
-   └─ Schedule auto-destruction
-
-2. EXECUTE
-   ├─ Pre-sync: Pull memories from hub
-   ├─ Run user task
-   └─ Post-sync: Push learning to hub
-
-3. LEARN
-   ├─ Query past experiences
-   ├─ Execute with context
-   └─ Store episode (reward, critique)
-
-4. DESTROY
-   ├─ Final sync to hub
-   ├─ Close local database
-   └─ Clear resources
-   └─ Memory persists in hub
-```
-
-### Federation Topology
-
-```
-                   Global Hub
-                  /     |     \
-                /       |       \
-            EU Hub   US Hub   AP Hub
-           /    \    /    \   /    \
-        Edge  Edge Edge  Edge Edge  Edge
-        Nodes Nodes Nodes Nodes Nodes Nodes
-```
-
-**Sync Latency:**
-- Edge → Regional Hub: <10ms
-- Regional Hub → Global Hub: ~50ms
-- Global Hub → Other Regional Hubs: ~100ms
-- Total propagation: <5 minutes
-
-### Conflict Resolution
-
-Uses **Vector Clocks + CRDTs** for automatic conflict resolution:
-
-```typescript
-// Agent A updates record at t=1
-vectorClock: { 'agent-a': 1, 'agent-b': 0 }
-
-// Agent B updates same record at t=2 (concurrent)
-vectorClock: { 'agent-a': 0, 'agent-b': 1 }
-
-// Conflict detected (neither dominates)
-// Resolution: Last-write-wins (higher timestamp)
-```
-
-## Security
-
-### Authentication Flow
-
-```
-1. Agent spawns
-   └─ SecurityManager.createAgentToken()
-      ├─ JWT with agentId, tenantId, expiry
-      └─ Signed with HMAC-SHA256
-
-2. Hub connection
-   ├─ mTLS handshake (mutual certificate verification)
-   ├─ JWT token validation
-   └─ Tenant access check
-
-3. Data encryption
-   ├─ Get per-tenant encryption keys
-   ├─ AES-256-GCM encryption
-   └─ Store encrypted data with auth tag
-```
-
-### Compliance
-
-**GDPR:**
-- Data residency (EU data stays in EU)
-- Right to erasure (delete all tenant memories)
-- Encryption at rest and in transit
-
-**HIPAA:**
-- PHI encryption (AES-256)
-- Audit logging
-- Access control
-
-**SOC2:**
-- Security monitoring
-- Access logs
-- Incident response
-
-## Performance
-
-### Benchmarks
-
-| Operation | Latency | Throughput |
-|-----------|---------|------------|
-| Agent spawn | <50ms | 1000 agents/sec |
-| Memory query (local) | <5ms | 10k queries/sec |
-| Memory query (hub) | <50ms | 2k queries/sec |
-| Sync operation | <100ms | 500 syncs/sec |
-| Episode storage | <10ms | 5k writes/sec |
-
-### Scalability
-
-- **Agents**: 100k concurrent agents per hub
-- **Tenants**: 10k tenants per hub
-- **Memories**: 100M memories per hub
-- **Regional hubs**: Unlimited (horizontal scaling)
-
-## Installation
-
-```bash
-npm install agentic-flow
-```
-
-## Configuration
-
-### Environment Variables
-
-```bash
-# Federation hub endpoint
-FEDERATION_HUB_ENDPOINT=quic://hub.agentdb.io:4433
-
-# Security
-JWT_SECRET=your-secret-key
-ENABLE_MTLS=true
-
-# Regional hubs (optional)
-EU_HUB=quic://hub-eu.agentdb.io:4433
-US_HUB=quic://hub-us.agentdb.io:4433
-AP_HUB=quic://hub-ap.agentdb.io:4433
-```
-
-### Hub Configuration
-
-```typescript
-// hub-config.ts
-export const hubConfig = {
-  topology: 'hub-and-spoke', // or 'mesh', 'hierarchical'
-  maxAgents: 100000,
-  syncInterval: 5000, // 5 seconds
-  enableMTLS: true,
-  certPath: '/path/to/cert.pem',
-  keyPath: '/path/to/key.pem',
-  caPath: '/path/to/ca.pem'
-};
-```
-
-## Testing
-
-Run the federation test suite:
-
-```bash
-# Run all tests
-npm test tests/federation/test-ephemeral-agent.ts
-
-# Build TypeScript first
-npm run build
-tsx tests/federation/test-ephemeral-agent.ts
-```
-
-**Test Coverage:**
-- ✅ Agent spawn and lifecycle
-- ✅ Task execution with memory access
-- ✅ Memory query and storage
-- ✅ Automatic expiration
-- ✅ Multiple concurrent agents
-- ✅ Tenant isolation
-- ✅ Federation sync (when hub available)
-
-## API Reference
-
-### EphemeralAgent
-
-```typescript
-class EphemeralAgent {
-  // Spawn new agent
-  static async spawn(config: EphemeralAgentConfig): Promise<EphemeralAgent>
-
-  // Execute task with memory access
-  async execute<T>(task: (db: AgentDB, context: AgentContext) => Promise<T>): Promise<T>
-
-  // Query memories
-  async queryMemories(task: string, k?: number): Promise<any[]>
-
-  // Store learning episode
-  async storeEpisode(episode: {
-    task: string;
-    input: string;
-    output: string;
-    reward: number;
-    critique?: string;
-  }): Promise<void>
-
-  // Get remaining lifetime
-  getRemainingLifetime(): number
-
-  // Check if alive
-  isAlive(): boolean
-
-  // Manual cleanup
-  async destroy(): Promise<void>
-}
-```
-
-### FederationHub
-
-```typescript
-class FederationHub {
-  // Connect to hub
-  async connect(): Promise<void>
-
-  // Sync with hub
-  async sync(db: AgentDB): Promise<void>
-
-  // Disconnect
-  async disconnect(): Promise<void>
-
-  // Get sync stats
-  getSyncStats(): { lastSyncTime: number; vectorClock: Record<string, number> }
-}
-```
-
-### SecurityManager
-
-```typescript
-class SecurityManager {
-  // Create JWT token
-  async createAgentToken(payload: AgentTokenPayload): Promise<string>
-
-  // Verify JWT token
-  async verifyAgentToken(token: string): Promise<AgentTokenPayload>
-
-  // Encrypt data
-  async encrypt(data: string, tenantId: string): Promise<{ encrypted: string; authTag: string }>
-
-  // Decrypt data
-  async decrypt(encrypted: string, authTag: string, tenantId: string): Promise<string>
-
-  // Generate mTLS certificates
-  async generateMTLSCertificates(agentId: string): Promise<{ cert: string; key: string; ca: string }>
-
-  // Validate tenant access
-  validateTenantAccess(requestTenantId: string, dataTenantId: string): boolean
-}
-```
-
-## Roadmap
-
-- [ ] Production QUIC implementation (currently uses WebSocket fallback)
-- [ ] Multi-hub federation (global mesh)
-- [ ] Real-time streaming sync (push-based updates)
-- [ ] ML-based conflict resolution (learn from conflicts)
-- [ ] Blockchain anchoring (for audit trail)
-- [ ] WebAssembly QUIC client (for browser agents)
-
-## Support
-
-- **Documentation**: [Architecture Guide](../../../docs/architecture/FEDERATED-AGENTDB-EPHEMERAL-AGENTS.md)
-- **Issues**: [GitHub Issues](https://github.com/ruvnet/agentic-flow/issues)
-- **Discord**: [Join our community](https://discord.gg/agentic-flow)
-
-## License
-
-MIT License - see [LICENSE](../../../LICENSE) for details.
-
----
-
-**Built with ❤️ by [@ruvnet](https://github.com/ruvnet)**
-
-**Powered by**: AgentDB (150x faster vector search) + QUIC (low-latency sync) + Zero-trust security

package/agentic-flow/memory-backup.json

@@ -1,48 +0,0 @@
-{
-  "default": [
-    {
-      "key": "test-validation",
-      "value": "all systems working",
-      "namespace": "default",
-      "timestamp": 1759669781417
-    },
-    {
-      "key": "direct-test",
-      "value": "MCP confirmed working",
-      "namespace": "default",
-      "timestamp": 1759670241353
-    },
-    {
-      "key": "gemini-mcp-test",
-      "value": "MCP tools working through Gemini proxy!",
-      "namespace": "default",
-      "timestamp": 1759670796156
-    },
-    {
-      "key": "v1.1.11-test",
-      "value": "MCP tool forwarding confirmed working",
-      "namespace": "default",
-      "timestamp": 1759670863764
-    },
-    {
-      "key": "version",
-      "value": "test-v1.1.11",
-      "namespace": "default",
-      "timestamp": 1759671813378
-    },
-    {
-      "key": "test-key",
-      "value": "Testing claude-flow memory system",
-      "namespace": "default",
-      "timestamp": 1760323905426,
-      "redacted": false
-    },
-    {
-      "key": "api_key",
-      "value": "sk-ant-test123",
-      "namespace": "default",
-      "timestamp": 1760323939358,
-      "redacted": false
-    }
-  ]
-}