docs: finalize professional README and technical guides

Author: gitsofaryan

README.md

@@ -1,144 +1,176 @@
-# 🧠 Agent DB: Decentralized Memory for AI Agents
+# 🤖 AgentDB: The Decentralized Memory Protocol for AI Agents
 
-> **Persistent, encrypted, and permission-controlled memory for autonomous AI agents powered entirely by Web3 infrastructure.**
-
-Built on **Storacha**, **IPNS**, **UCAN**, and **Zama fhEVM**, Agent DB is an enterprise-grade platform for endowing AI agents with cross-platform reasoning continuity and verifiable capability delegation.
+**AgentDB** is a high-performance, decentralized memory infrastructure layer that provides AI agents with permanent, sovereign, and collaborative "brains." Built on **Storacha (IPFS/Filecoin)**, **UCAN**, and **X25519**, it transforms ephemeral agent sessions into a global, device-agnostic knowledge graph. 
 
 ---
 
-## 🏗️ Platform Architecture
+## 🌎 The Vision: Solving the "AI Lobotomy"
+
+Today, AI agents suffer from a fundamental flaw: **amnesia**. Every time a process restarts, a server crashes, or a container scales down, the agent is "lobotomized." Their memory is either trapped in volatile local RAM or locked inside centralized SaaS databases that other agents cannot access. 
 
-Agent DB is a decentralized memory and sovereignty engine for autonomous AI. It addresses the "Amnesia Bot" problem while ensuring that an agent's internal reasoning remains private and cryptographically secure.
+**AgentDB changes the fundamental architecture of AI:**
 
-1. **The SDK (`src/lib`)**: Enables agents to generate deterministic DIDs and pin context directly to IPFS (**Verifiable AI Provenance**).
-2. **ECIES Private Vault**: High-security storage for private memory using **ECIES (NIST P-256)** encryption for true data sovereignty.
-3. **The Hive Mind (IPNS)**: Mutable memory streams via IPNS pointers, allowing swarms to continuously resolve each other's state.
-4. **Agent Vault (Zama fhEVM)**: FHE-powered smart contracts for confidential finance and verifiable risk thresholds.
-5. **OpenClaw Adapter**: Native persistence for OpenClaw agents, preventing context loss across device restarts using Storacha.
-6. **Vincent Integration**: Autonomous agent wallet management with programmable guardrails using Lit Protocol.
+1. **From Local Silos to a Global Graph**: Agents no longer store "thoughts" on a single hard drive. They serialize their context and pin it to the decentralized web (Storacha), making their memory accessible from anywhere on Earth.
+2. **From Isolation to Cryptographic Collaboration**: AI models are moving towards multi-agent swarms. Using **UCAN delegations**, Agent B can cryptographically "hand off" its context to Agent A without exposing private keys or relying on centralized middleware.
+3. **From Centralized to Sovereign**: You—and your agents—own the memory. There is no API gatekeeper. It is raw, encrypted data pinned to the permanent web, verifiable on-chain.
 
 ---
 
-## 🚀 Running the Platform
+## 🏗️ Technical Architecture & Under-the-Hood
 
-### 0. Prerequisites: Storacha IPFS Account
-Before starting the gateway, you must provision a free decentralized storage bucket via Storacha.
-1. `npm install -g @storacha/cli`
-2. `storacha login`
-3. `storacha space create "MyAgentNode"`
-4. `storacha space use <SPACE_DID>`
+AgentDB operates as a fully peer-to-peer memory layer comprising three core modules. These modules ensure that data is not only stored permanently but retrieved at speeds competitive with Web2 databases.
 
-*(If skipped, the gateway will gracefully fallback to simulated, local-only CIDs).*
+### 🧩 1. Identity & Authorization Layer (`ucan.ts`)
+We standardize agent identification using **Ed25519 DIDs** (Decentralized Identifiers). An agent *is* its private key.
+- **Sovereign Agents**: Every agent generates a DID upon initialization (`UcanService.createIdentity()`).
+- **Capability Delegation**: When Agent B finishes researching a topic, it issues a cryptographically signed "ticket" (UCAN) to Agent A (`UcanService.delegate()`). This ticket encodes the specific IPFS CID and the `agent/read` capability.
+- **Zero-Trust Verification**: Access isn't granted by checking a database; the proof is baked into the math of the UCAN token itself (`UcanService.verifyDelegation()`).
 
-### 1. Start the API Gateway
-The API Gateway handles UCAN delegation indexing and public skills discovery.
+### 🧩 2. Storage & Retrieval Layer (`storacha.ts`)
+Powered by **Storacha** (the hot storage layer for Filecoin), we treat IPFS as a high-speed agent backend.
+- **Gateway Racing Engine**: The biggest critique of IPFS is latency. AgentDB implements a proprietary retrieval strategy that queries 4+ IPFS gateways (Cloudflare, Pinata, IPFS.io, Storacha) simultaneously. The first one to return the data wins, consistently delivering **sub-second response times** (~500ms).
+- **Stable IPNS Mapping**: To solve the problem of moving agents across devices, AgentDB derives a stable mutable pointer directly from an agent's seed (`StorachaService.deriveIpnsName()`). This creates a permanent, deterministic "Home Base" (Session Registry) for the agent's memory map, regardless of the physical hardware it runs on.
 
-```bash
-# Install platform dependencies
-npm install
+### 🧩 3. Security Layer (`encryption.ts`)
+For sensitive data, we implement hardware-grade protection using **X25519 (Curve25519)**.
+- **ECIES Implementation**: AgentDB combines Diffie-Hellman key exchange with **AES-256-GCM**. When Agent B wants to write a private thought, it encrypts the data so it is mathematically unreadable by anyone but the owner and authorized delegates (`EncryptionService.encrypt()`).
 
-# Start the discovery gateway
-npm run server
-```
+---
 
-The gateway will run on `http://localhost:3001` with strict CORS and rate-limiting enabled for production stability.
+## 🧠 Comprehensive Ecosystem Integrations
 
-### 2. Start the Frontend Dashboard
-The Next.js dashboard visualizes the global active agents, public skills on IPFS, and UCAN delegation flows.
+AgentDB acts as a drop-in persistence layer for the modern AI stack, enabling agents built on different frameworks to share a unified, decentralized memory.
 
-```bash
-cd frontend
-npm install
-npm run dev
-```
+### 🔹 [OpenClaw](https://github.com/openclaw/openclaw) Integration
+OpenClaw agents are brilliant but often lose their customized persona when deployed to new environments. `AgentDbOpenClawMemory` provides a permanent anchor:
+- **Persistent Persona (`resumeFromCid`)**: Instantly restores an agent's entire personality, learned preferences, and history from the decentralized web when it boots up.
+- **Auto-Checkpointing (`commitToStoracha`)**: Automatically snapshots the agent's state to IPFS after conversations.
 
-Navigate to `http://localhost:3000` to view the live Globe visualization.
+### 🔹 [LangChain](https://js.langchain.com/) Integration
+`AgentDbLangchainMemory` replaces the ephemeral `BufferMemory` module standard in LangChain:
+- **Streaming "Hive Mind" IPNS**: Instead of just saving static JSON, it continuously updates a single mutable pointer as the conversation progresses. This allows external tools or other agents to "tune in" to a live stream of the agent's thought process.
+
+### 🔹 [Lit Protocol](https://litprotocol.com/) Integration
+Agents need agency. `LitVincentService` connects agent memory to programmable on-chain wallets:
+- **Programmable Wallets (`provisionAgentWallet`)**: Uses Lit PKPs to generate non-custodial wallets specifically for the agent. This allows the AgentDB agent to autonomously pay gas fees or its own Storacha storage bills, creating a fully self-sustaining AI entity.
 
 ---
 
-## 🤖 Model Context Protocol (MCP) Server
-Agent DB is now accessible via MCP! This allows any AI model (Claude, Gemini, Cursor) to natively use decentralized memory, encryption, and delegation tools.
+## 💻 Developer Integration Guide
 
-### 🔌 Connect to MCP
-To add Agent DB to your AI agent environment, use the following command or configuration:
+Integrating AgentDB into your custom AI project takes less than 10 lines of code.
 
-```bash
-# Start locally
-npm run mcp
-```
+### 1. Initialization and Public Memory
+Start by creating a stable identity and pushing data to the public IPFS network.
 
-**Claude Desktop Config:**
-```json
-"mcpServers": {
-  "agent-db": {
-    "command": "npx",
-    "args": ["-y", "@arienjain/agent-db", "mcp"]
-  }
-}
-```
+```typescript
+import { AgentRuntime } from '@arienjain/agent-db';
 
-**Exposed Tools:**
-- `init_agent`: Login with your seed phrase.
-- `store_memory` / `retrieve_memory`: Decentralized IPFS storage.
-- `store_private_memory` / `retrieve_private_memory`: High-security ECIES vault.
-- `delegate_access`: Issue UCAN permissions to other agents.
+// Initialize agent deterministically from a secure seed.
+// This guarantees it will resolve the same IPNS memory registry anywhere.
+const agent = await AgentRuntime.loadFromSeed(process.env.AGENT_SEED);
+console.log(`Agent Online: ${agent.did}`);
 
----
+// Store a complex, nested context directly to Storacha (IPFS)
+const memoryCid = await agent.storePublicMemory({
+    mission: "Alpha Sector Scan",
+    insights: ["Anomalous energy detected", "Possible alien artifact"],
+    metrics: { confidence: 0.95 }
+});
+
+console.log(`Memory permanently pinned at CID: ${memoryCid}`);
+```
 
-## 🔐 Smart Contract Vault (Zama fhEVM)
+### 2. The Agent Handoff (Collaboration)
+Share memory with another agent using UCANs.
 
-For data that cannot be public on IPFS, Agent DB leverages Zama's Fully Homomorphic Encryption.
+```typescript
+// Agent A wants to give Agent B permission to read its data
+const agentBDid = "did:key:z6Mk...Agent_B_Address";
 
-1.  Agents encrypt their context locally.
-2.  The FHE payload is submitted to the `EncryptedAgentMemory` contract.
-3.  Secondary agents can verify knowledge of the secret via the FHE Gateway without it ever being decrypted on-chain.
+// Generate a cryptographic delegation valid for 24 hours
+const token = await agent.delegateTo(
+    { did: () => agentBDid }, 
+    'agent/read', 
+    24
+);
 
-### 3. Running Hackathon Bounty Demos
-We have prepared specific demonstrators for the PL_Genesis bounty tracks. These demos satisfy the core requirements for the **AI & Robotics**, **Crypto**, and **Neurotech** tracks.
+// Publish token to IPFS for Agent B to pick up
+const tokenCid = await agent.exportDelegationForApi(token);
+// Or send token directly over API/WebSocket
+```
 
-```bash
-# 🤖 AI & Robotics: OpenClaw Persistence (Storacha)
-npm run demo:openclaw
+### 3. Private Memory (Military-Grade Encryption)
+```typescript
+// Encrypts memory so NO ONE else on the IPFS network can read it
+const secureCid = await agent.storePrivateMemory({
+    api_keys: { openai: "sk-..." },
+    financial_strategy: "buy the dip"
+});
 
-# 🔗 Crypto: Agent Registry on Filecoin Calibration
-npm run demo:filecoin
+// Later, the agent decrypts it locally
+const secureData = await agent.retrievePrivateMemory(secureCid);
+```
 
-# ⚖️ Crypto/DeFi: Zama fhEVM Confidential Finance
-npm run demo:defi
+---
 
-# 🛡️ Crypto/KeyMgmt: Lit Protocol Vincent Wallet Logic
-npm run demo:lit
+## 🛰️ Advanced Architectural Features
+
+### 🧩 Agent Migration (Device-Agnosticism)
+AgentDB removes the "local file" bottleneck entirely. Because the session registry is mapped to IPNS via the agent's seed, you can destroy the server, boot the agent on a mobile device, and recover perfectly.
+
+```mermaid
+sequenceDiagram
+    participant H as Environment A (Desktop)
+    participant N as IPNS (Decentralized Registry)
+    participant C as Environment B (Cloud)
+    
+    H->>H: Derive Stable IPNS from Seed
+    H->>N: Update Registry (Session: Chat_Alice -> CID_123)
+    Note over H: Power Failure / Machine Wiped
+    Note over C: Agent Starts with SAME Seed
+    C->>C: Resolve IPNS Registry
+    N-->>C: Returns Session Map
+    Note over C: Agent recovered all past chats with ZERO local state
 ```
 
-### 🛡️ Production Hardening Proofs
-The system has been hardened for real-world deployments. You can verify the security and resilience features here:
+### 🧩 Concurrency Guards
+In multi-agent architectures, two agents might try to update the IPNS registry simultaneously. AgentDB implements "Sync-before-Write" logic to fetch the latest global state before publishing, preventing data overwrites and collisions.
 
-```bash
-# 🔐 Private Vault (ECIES Security Verification)
-npx tsx src/test-encryption.ts
+---
 
-# 💾 Resilience (Handoff & Persistence Verification)
-npx tsx src/test-persistence.ts
+## 🛠️ MCP Ecosystem: For LLMs
 
-# 🛠️ Validation & DX (Zod Schema & Error Handling)
-npx tsx src/test-dx.ts
-```
+The **AgentDB MCP Server** enables Model Context Protocol-compatible clients (like Claude Desktop or Cursor) to natively use decentralized memory via a simple UI.
+
+- **`list_sessions`**: Command the LLM to browse the agent's decentralized memory tree.
+- **`resolve_session`**: Pull the full context of a past chat right into the LLM's prompt window.
+- **`store_private_memory`**: Command the LLM to encrypt sensitive output for its "private eyes" only.
+- **`delegate_access`**: Ask the LLM to issue a UCAN permission to a fellow agent.
 
 ---
 
-## 📦 For Agent Developers (SDK)
+## 🧪 Try the Included Simulations
 
-Are you an AI developer looking to integrate persistent memory into your Discord bot, LangChain agent, or CLI tool? 
+We've bundled fully functional simulations illustrating AgentDB's power. Run them locally:
 
-**Do not read this repository manual.**
+```bash
+# 1. Cross-Agent Handoff Simulation
+# Watch Agent B store a report and issue a UCAN for Agent A to read it.
+npx tsx src/demo-mcp-simulation.ts
 
-Instead, please consult the lightweight SDK Developer Guide:
-👉 [Read the `@arienjain/agent-db` Node.js Developer Documentation](README_NPM.md)
+# 2. Decentralized Migration Test
+# Watch an agent store data, wipe its local storage, and recover from IPNS.
+npx tsx src/demo-migration.ts
 
----
+# 3. High-Performance Large Data Test
+# Proves Storacha integration handles 20MB+ files (like RAG vector stores), not just tiny JSONs.
+npx tsx src/demo-large-data.ts
 
-## 🤝 Contributing
-Agent DB is an open protocol. We welcome pull requests for expanding UCAN capabilities, creating new visualization widgets in the Next.js frontend, or adding additional fhEVM smart contract capabilities.
+# 4. Multi-Context Switching
+# Watch an agent juggle parallel workflows natively.
+npx tsx src/demo-multi-context.ts
+```
 
-## 📄 License
-MIT License.
+---
+*Built from the ground up to standardize how artificial intelligence remembers.*

docs/performance_guide.md

@@ -0,0 +1,58 @@
+# ⚡ AgentDB: Production Scaling & Performance
+
+To handle **10 Million tokens** and achieve **Sub-second Retrieval**, we recommend the following professional architectural patterns.
+
+## 1. Fast Data Retrieval (Sub-Second Latency)
+
+IPFS is decentralized, which can introduce latency. To fix this:
+
+### A. Local LRU Caching
+Don't fetch from the network if you just fetched it 5 minutes ago.
+- **How**: Implement an in-memory or Redis cache in the `AgentRuntime`.
+- **Latency**: 5ms (Cache) vs 500ms+ (IPFS).
+
+### B. Gateway Racing
+The `storacha.link` gateway is great, but sometimes Cloudflare or Pinata is faster for a specific region.
+- **How**: Fetch from 3 gateways in parallel (`Promise.any`) and return the first winner.
+- **Gateways to use**: `https://storacha.link`, `https://cloudflare-ipfs.com`, `https://w3s.link`.
+
+### C. Pre-fetching
+If the agent is in Chat Session A, start pre-fetching the last 3 CIDs in the background before the user even types a response.
+
+---
+
+## 2. Managing 10M Token Contexts
+
+Loading 10 Million tokens into an LLM is impossible or extremely expensive. Instead, use **Tiered Semantic Memory**.
+
+### Layer 1: The "Active Mind" (0-10k Tokens)
+- **Format**: Raw message history.
+- **Storage**: Local RAM / Session State.
+
+### Layer 2: The "Short-Term Memory" (10k-500k Tokens)
+- **Strategy**: **Recursive Summarization**.
+- **How**: Every time a session hits 50 messages, trigger an LLM "Memory Compression" task.
+- **Result**: Turn 100 messages into 5 bullet points. Store the bullet points as a new CID in the "Semantic" namespace.
+
+### Layer 3: The "Deep Knowledge" (10M+ Tokens)
+- **Strategy**: **Decentralized RAG**.
+- **How**: 
+  1. Chunk the 10M tokens into 1k chunks.
+  2. Generate vector embeddings for each chunk.
+  3. Store the **Vector Index** (the map of embeddings) on IPFS.
+  4. At runtime, the agent only downloads the **Index**, finds the 3 most relevant CIDs, and fetches ONLY those.
+- **Benefit**: You only pay for 3 small CIDs instead of 10 million tokens of LLM context.
+
+## Example Implementation Pattern (RAG)
+
+```typescript
+// Instead of one big file, store a manifest
+const manifest = {
+    index_cid: "bafy...", // Vector index
+    chunks: [
+        { id: 1, cid: "bafy-chunk-1" },
+        { id: 2, cid: "bafy-chunk-2" },
+        // ... 10,000 more
+    ]
+};
+```

docs/strategic_analysis.md

@@ -0,0 +1,45 @@
+# 🔍 Strategic Analysis: Pain Points & Direction
+
+After scanning the codebase and evaluating the "Agent B ➡️ Agent A" vision, here is the critical analysis of where AgentDB stands and where it needs to go.
+
+## 🔴 Technical Pain Points (The "Hard Bits")
+
+### 1. The "Local Index" Silo
+**Problem**: The SDK currently saves the `Namespace Index` (mapping `CHAT_ALICE` to a CID) in a local `.agent_storage/` folder.
+- **Pain**: If your agent moves from a laptop to a cloud server, it becomes "blind." It can't find Alice's chat even though the data is safe on IPFS.
+- **Solution**: The Index itself must be stored in a **Mutable Pointer (IPNS)** tied to the Agent's DID.
+
+### 2. IPNS Revision Collisions
+**Problem**: When multiple agents (or two instances of the same agent) update the same memory stream, they might overwrite each other's updates.
+- **Pain**: IPFS identity is eventual. Concurrent writes lead to data loss.
+- **Solution**: Implement a "Check-and-Set" (CAS) logic or use a centralized sequencer (like a Filecoin actor) for high-concurrency streams.
+
+### 3. Key Rotation vs. Data Permanence
+**Problem**: Encryption keys are derived from the current signer.
+- **Pain**: If an agent loses its private key or wants to rotate to a more secure hardware wallet, it loses access to all historical `storePrivateMemory` data.
+- **Solution**: Decouple Identity (DID) from Encryption Keys. Use a "Key Management Service" (like Lit Protocol, which is already in your `lib/`) to handle multi-party decryption.
+
+### 4. Discovery UX
+**Problem**: Agent A needs to "know" the CID from Agent B.
+- **Pain**: Copy-pasting CIDs is not for agents.
+- **Solution**: Build a "Global Session Registry" (the blockchain part). Agent B lists the Session ID on-chain; Agent A looks up the Session ID to find the latest CID.
+
+---
+
+## 🚀 Future Direction: Where is this going?
+
+### Phase 1: The "Handoff" Standard (Current)
+You are successfully solving the **Context Portability** problem. You've made it possible for Agent B (Field Ops) to give its "brain" to Agent A (Analyst). 
+
+### Phase 2: The "Hive Mind" (Incoming)
+The project is heading towards **Collective Agent Intelligence**. Instead of isolated agents, you are building a shared, encrypted knowledge graph where agents can "subscribe" to each other's specialized memories.
+
+### Phase 3: Sovereign Personal Databases
+Eventually, this becomes a replacement for Google Drive for Agents. A user owns a single "Storacha Space" and delegates restricted UCAN access to different AI services (Recipe Agent, Tax Agent, Health Agent) which all write to the same decentralized DB.
+
+---
+
+## 🎯 Final Verdict
+**Current Status**: Solid technical foundation for agent memory transfers.
+**Immediate Next Step**: Move the `local_index.json` to IPNS so agents are truly "Device Agnostic."
+**Long-term Play**: Become the **gRPC/SQL equivalent** for the Agent-to-Agent economy.