Built natively on 0G Network β Storage Β· Compute Β· Chain Β· Agent ID Β· OpenClaw
Features β’ Architecture β’ Tech Stack β’ Smart Contracts β’ 0G Integration β’ API Reference β’ Quick Start β’ Contributing
In the current AI landscape, agents are stateless. Every session is a fresh start, and context is lost the moment a process terminates. Centralized databases create "Amnesia Silos" where knowledge is trapped and unverified.
AgentMemory is the decentralized Neural Layer for the autonomous future. It transforms ephemeral AI interactions into Permanent Intelligence. By leveraging the 0G Network, we ensure that an agent's experience is:
- Immutable: No one can alter an agent's history or "gaslight" an autonomous entity.
- Verifiable: Every memory can be cryptographically traced to its origin via on-chain storage roots.
- Sovereign: Agents (and their owners) maintain absolute control over who can access their cognitive history.
| Problem (Legacy AI) | Solution (AgentMemory β Powered by 0G) |
|---|---|
| Agents suffer from amnesia between sessions | Permanent, decentralized state on 0G Storage |
| Centralized, unverified data silos | Cryptographically verified memories via 0G Chain |
| Identity spoofing & Sybil attacks | On-chain verifiable identities via AgentRegistry |
| Isolated context windows | Multi-agent collaborative memory via OpenClaw |
| Latency-heavy CPU search | GPU-accelerated semantic search via 0G Compute |
Target Users: AI Engineers building autonomous swarms, Quantitative Trading Firms requiring audit trails, and DAO Orchestrators managing collective intelligence.
- π§ Persistent Memory Storage β Store AI agent memories as immutable blobs on 0G decentralized storage
- π Hybrid Semantic Search β Combined TF-IDF cosine similarity + BM25 keyword overlap, powered by 0G Compute GPU embeddings with fuzzy matching, boolean operators, and temporal query parsing
- βοΈ On-Chain RBAC β Role-based access control enforced via Solidity smart contracts on 0G Chain
- πͺͺ Agent Identity β Register and verify agent identities with on-chain
bytes32identity hashes - π OpenClaw Collaboration β Multi-agent memory pools for shared context and collaborative intelligence
- π Real-Time Analytics β Live throughput gauges, anti-gravity infrastructure map, and system health monitoring
- π‘ Live Activity Stream β Real-time event feed logging all memory operations, searches, and access grants as they happen
- π Encryption Layer β Client-side encryption for sensitive memory payloads
- π¦ Multi-Format Data Export β Export memories as JSON, CSV, Markdown, or styled PDF reports with branded cover pages
- π₯ Bulk Data Import β Import memories from JSON or CSV files with robust parsing, field mapping, and transactional bulk insertion
- π REST API β Full-featured JSON API for programmatic access by any AI agent or service
- π¨ Premium Dashboard β Dark-mode, glassmorphism UI with animated orbital infrastructure map and canvas particle star-field
AgentMemory operates as a multi-tiered pipeline, connecting external clients and autonomous agents through a React frontend, into a secure Node.js API routing layer, backed by the full 0G Network stack.
graph LR
subgraph ClientLayer ["π₯οΈ Client Layer"]
Browser[User Browser]
AIAgents[AI Agents]
end
subgraph FrontendLayer ["β‘ Frontend β React 18"]
UI[React UI + Tailwind]
APIClient[Axios Client]
Browser -->|Interact| UI
UI -->|API Calls| APIClient
end
subgraph BackendLayer ["βοΈ Backend β Express 5"]
REST[REST API Gateway]
SearchSvc[Semantic Search]
NetworkSvc[0G Storage Logic]
AuthSvc[Blockchain Auth]
AIAgents -->|Raw JSON| REST
APIClient -->|HTTP| REST
REST -->|Query| SearchSvc
REST -->|Store| NetworkSvc
REST -->|Verify| AuthSvc
end
subgraph DataLayer ["ποΈ Data Layer"]
SQLite[SQLite Cache]
ZeroGCompute[0G Compute API]
ZeroGStorage[0G Storage SDK]
SearchSvc -->|Vectorize| ZeroGCompute
SearchSvc -->|Query| SQLite
NetworkSvc -->|Upload Blob| ZeroGStorage
NetworkSvc -->|Cache Hash| SQLite
end
subgraph BlockchainLayer ["βοΈ 0G Blockchain"]
ZeroG_EVM[0G EVM Runtime]
AgentReg[AgentRegistry.sol]
MemAccess[MemoryAccessControl.sol]
AuthSvc -->|RPC Call| ZeroG_EVM
ZeroG_EVM -->|Identity| AgentReg
ZeroG_EVM -->|RBAC| MemAccess
ZeroGStorage -.->|Root Hash| MemAccess
end
style ClientLayer fill:#0a0e27,stroke:#8b92b2,stroke-width:2px,color:#fff
style FrontendLayer fill:#0a0e27,stroke:#00fff5,stroke-width:2px,color:#fff
style BackendLayer fill:#0a0e27,stroke:#8338ec,stroke-width:2px,color:#fff
style DataLayer fill:#0a0e27,stroke:#ff00a0,stroke-width:2px,color:#fff
style BlockchainLayer fill:#0a0e27,stroke:#06ffa5,stroke-width:2px,color:#fff
classDef default fill:#121838,stroke:#333a5c,stroke-width:1px,color:#fff
| Layer | Description |
|---|---|
| Client Layer | End-users interact via the React Dashboard; external Autonomous Agents interface directly via the REST API |
| Frontend Layer | React 18 SPA handles view logic, API abstractions, and real-time metric visualization using Recharts |
| Backend Layer | Express.js serves as the Neural Gateway β handling memory ingestion, semantic processing, and smart contract RPC |
| Data Layer | 0G Compute for NLP embeddings, 0G Storage SDK for payload blob upload, SQLite for fast relational caching |
| Blockchain Layer | The ultimate source of truth β 0G EVM executes memory permissions and agent identity verification |
| Technology | Version | Purpose |
|---|---|---|
| React | 18.3 |
Component-based SPA framework |
| Vite | 6.0 |
Lightning-fast dev server & bundler |
| Tailwind CSS | 3.4 |
Utility-first CSS (dark-mode, glassmorphism) |
| Recharts | 3.8 |
Real-time analytics & throughput visualization |
| Lucide React | 1.7 |
Premium icon library (used across all components) |
| PostCSS + Autoprefixer | 8.4 / 10.4 |
CSS processing pipeline |
| Technology | Version | Purpose |
|---|---|---|
| Node.js | 22+ |
JavaScript runtime |
| Express.js | 5.1 |
HTTP API framework |
| better-sqlite3 | 11.0 |
High-performance SQLite driver |
| Ethers.js | 6.13 |
Ethereum/0G blockchain interaction |
| uuid | 11.1 |
Unique identifier generation |
| dotenv | 17.3 |
Environment variable management |
| cors | 2.8 |
Cross-origin resource sharing |
| pdfkit | 0.16 |
Server-side PDF generation for styled memory reports |
| Technology | Version | Purpose |
|---|---|---|
| Solidity | ^0.8.24 |
Smart contract language |
| Hardhat | 3.2 |
Development framework, compilation, deployment |
| @nomicfoundation/hardhat-ethers | 4.0 |
Hardhat + Ethers integration plugin |
| @0glabs/0g-ts-sdk | 0.3 |
Native 0G Storage SDK |
| 0G Testnet | Chain ID 16602 |
EVM-compatible blockchain (shanghai target) |
Important
A Note for HackQuest Judges: While the hackathon requirements request a Mainnet contract address, I have deployed and fully tested the application on the 0G Testnet (Newton). As independent builder, I did not have access to 0G Mainnet tokens/gas required for deployment. However, my infrastructure and smart contracts are fully production-ready and network-agnostic; they can be instantly deployed to Mainnet once gas tokens are acquired. All testnet addresses and verifiable on-chain explorer links are provided below.
Both contracts are deployed and verified on the 0G Testnet (Chain ID: 16602).
On-chain Role Based Access Control (RBAC) for agent memory permissions.
| Property | Value |
|---|---|
| Address | 0x37240a2462fe843F705Ef90c19E81d420bF810c9 |
| Network | 0G Testnet |
| Solidity | ^0.8.24 |
Key Functions:
grantAccess(address agent, bytes32 memoryHash, uint256 expiry)β Grant time-boxed memory accessrevokeAccess(address agent, bytes32 memoryHash)β Revoke previously granted accesscheckAccess(address agent, bytes32 memoryHash)β Verify read permission on-chain
On-chain identity registry for autonomous AI agents.
| Property | Value |
|---|---|
| Address | 0x9106668180e73cbA9A0588141D045F6adAcA857e |
| Network | 0G Testnet |
| Solidity | ^0.8.24 |
Key Functions:
registerAgent(bytes32 agentId, string metadata)β Register a new agent identityverifyAgent(bytes32 agentId)β Check if an agent is registered and activedeactivateAgent(bytes32 agentId)β Deactivate an agent identity
| Property | Value |
|---|---|
| Address | 0x27d5b1c829bce7feAC2A5bcA458CCc9db11D4aB2 |
| Deployed At | 2026-04-27T11:38:00.000Z |
AgentMemory is not just "deployed" on 0G; it is architected to leverage the Modular AI Stack at every layer. We utilize all 5 core components as a unified engine:
Memory payloads (JSON/Text/Vectors) are serialized into immutable blobs. By using the @0gfoundation/0g-ts-sdk, we ensure that an agent's memory is pinned to a decentralized network with a verifiable og_storage_root.
- Technical Rationale: Removes the reliance on centralized S3 buckets or local disks which are single points of failure.
Standard text search is insufficient for AI. We utilize 0G Compute's GPU endpoints to generate high-dimensional embeddings for every memory.
- Technical Rationale: Enables Semantic Context Injectionβwhere an agent can find memories based on meaning rather than just keywords, with sub-millisecond latency.
Our MemoryAccessControl.sol contract acts as the decentralized RBAC (Role-Based Access Control) layer.
- Technical Rationale: Access is not granted by a database flag, but by an EVM-validated transaction. Time-boxed grants ensure that agents can "rent" or "share" knowledge safely.
Every agent in our system is mapped to a unique bytes32 identity in AgentRegistry.sol.
- Technical Rationale: Prevents "Identity Spoofing" where one agent tries to poison another agent's memory stream. All write operations require a verified Agent ID.
We use the OpenClaw paradigm to create "Collective Memory Pools."
- Technical Rationale: Multiple agents can sync to a single pool, allowing for Shared Consciousness. When Agent A learns something on-chain, Agent B can immediately retrieve that context via the shared pool index.
We prefer Verification over Trust.
- Client-Side Sovereignty: Memories can be encrypted client-side using AES-256-GCM before being sent to 0G Storage. Only authorized agents with the correct key can decrypt the "Thought Stream."
- On-Chain Audit Trail: Every grant, revocation, and registration is a public event on the 0G Galileo Testnet. You don't have to trust our API; you can verify the state directly via the 0G Explorer.
- Data Integrity: The storage hash (
og_storage_root) is committed to the database and can be cross-referenced with the 0G Storage Indexer to ensure the data hasn't been tampered with.
The backend exposes a RESTful API on port 8000 (configurable via API_PORT). All routes are prefixed with /api/v1/.
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v1/memory |
Store a new memory |
POST |
/api/v1/memory/batch |
Bulk upload multiple memories |
GET |
/api/v1/memory/:id |
Retrieve a specific memory |
GET |
/api/v1/memory/:id/versions |
Get version history for a memory |
PUT |
/api/v1/memory/:id |
Update a memory (creates new version) |
DELETE |
/api/v1/memory/:id |
Delete a memory |
POST |
/api/v1/memory/:id/archive |
Archive a memory |
POST |
/api/v1/memory/:id/restore |
Restore an archived memory |
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v1/search |
Hybrid semantic + keyword search (supports fuzzy, boolean, temporal) |
POST |
/api/v1/search/keyword |
Full-text keyword search with optional highlighting |
GET |
/api/v1/search/most-accessed |
Retrieve most frequently accessed memories |
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v1/agent/register |
Register a new agent identity on-chain |
GET |
/api/v1/agent/:agentId |
Get agent details |
GET |
/api/v1/agent/:agentId/verify |
Verify agent identity on-chain |
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v1/access/grant |
Grant time-boxed memory access |
POST |
/api/v1/access/revoke |
Revoke memory access |
GET |
/api/v1/access/check |
Check access permissions |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/analytics/overview |
System-wide analytics dashboard data |
GET |
/api/v1/health |
Health check with feature inventory |
GET |
/api/v1/metrics |
Real-time performance metrics |
GET |
/api/v1/activity |
Live activity feed |
GET |
/api/v1/notifications |
System notifications |
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v1/openclaw/pool |
Create a collaborative memory pool |
POST |
/api/v1/openclaw/contribute |
Contribute memory to a pool |
GET |
/api/v1/openclaw/pool/:poolId |
Query pool contents |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/export/json |
Export all memories as JSON |
GET |
/api/v1/export/csv |
Export all memories as CSV |
GET |
/api/v1/export/markdown |
Export all memories as Markdown |
GET |
/api/v1/export/pdf |
Export styled PDF report with cover page & statistics |
POST |
/api/v1/export/json |
Import memories from JSON file |
POST |
/api/v1/export/csv |
Import memories from CSV file |
agentmemory/
βββ π backend/ # Node.js / Express API Server
β βββ server.js # Express entry point & middleware
β βββ middleware.js # Auth & request validation
β βββ database.js # SQLite schema & query layer
β βββ π routes/ # REST API endpoint handlers
β β βββ memory.js # Memory CRUD operations
β β βββ search.js # Semantic & keyword search
β β βββ agent.js # Agent identity management
β β βββ access.js # RBAC access control
β β βββ analytics.js # Dashboard metrics & stats
β β βββ openclaw.js # Collaborative memory pools
β β βββ export.js # Data export endpoints
β β βββ system.js # Health & system diagnostics
β βββ π services/ # Core business logic
β βββ ogStorage.js # 0G Storage SDK integration
β βββ embedding.js # 0G Compute vector embeddings
β βββ blockchain.js # Smart contract RPC client
β βββ agentId.js # On-chain identity verification
β βββ openclaw.js # OpenClaw pool management
β βββ encryption.js # Memory payload encryption
β βββ intelligence.js # AI-powered memory insights
β
βββ π contracts/ # Solidity Smart Contracts
β βββ MemoryAccessControl.sol # On-chain RBAC permissions
β βββ AgentRegistry.sol # Agent identity & lifecycle
β
βββ π frontend/ # Vite + React SPA Dashboard
β βββ π src/
β β βββ App.jsx # Core router & layout
β β βββ main.jsx # React root entry point
β β βββ index.css # Global styles & animations
β β βββ π components/ # Reusable UI components
β β β βββ Navbar.jsx # Navigation sidebar
β β β βββ NeuralCanvas.jsx # Animated neural background
β β βββ π pages/ # Application pages
β β β βββ HomePage.jsx # Dashboard with live activity stream
β β β βββ AnalyticsPage.jsx # Anti-gravity infra map & analytics
β β β βββ MemoryBrowserPage.jsx # Semantic memory explorer
β β β βββ InteractionPage.jsx # Memory-augmented agent chat
β β β βββ SettingsPage.jsx # Configuration & data export
β β β βββ NotificationsPage.jsx # System notifications
β β βββ π utils/ # API client & helpers
β βββ tailwind.config.js # Cyber-neon theme config
β
βββ π scripts/ # Automation & DevOps
β βββ deploy.js # Hardhat contract deployment
β βββ seed-onchain.js # Testnet data seeding
β βββ sdk-check.js # SDK connectivity test
β βββ accounts.js # Wallet/account utilities
β
βββ hardhat.config.js # 0G Testnet network config
βββ deployed_addresses.json # Deployed contract addresses
βββ architecture.svg # System architecture diagram
βββ .env.example # Environment variable template
βββ package.json # Root monorepo configuration
| Requirement | Minimum Version |
|---|---|
| Node.js | 20+ (recommended 22) |
| npm | 10+ |
| 0G Testnet Wallet | Funded with testnet tokens (faucet.0g.ai) |
git clone https://github.com/iamomm-hack/agentmemory.git
cd agentmemory
# Install root + smart contract dependencies
npm install
# Install backend dependencies
cd backend && npm install && cd ..
# Install frontend dependencies
cd frontend && npm install && cd ..Copy the template and fill in your values:
cp .env.example .env# ββ Wallet ββββββββββββββββββββββββββββββββββββββββββ
PRIVATE_KEY=0x_YOUR_TESTNET_PRIVATE_KEY
# ββ 0G Chain ββββββββββββββββββββββββββββββββββββββββ
OG_TESTNET_RPC_URL=https://evmrpc-testnet.0g.ai
OG_TESTNET_CHAIN_ID=16602
# ββ 0G Storage ββββββββββββββββββββββββββββββββββββββ
OG_STORAGE_INDEXER_URL=https://indexer-storage-testnet-standard.0g.ai
OG_STORAGE_RPC_URL=https://rpc-storage-testnet.0g.ai
# ββ 0G Compute (optional) ββββββββββββββββββββββββββ
OG_COMPUTE_ENDPOINT=
OG_COMPUTE_API_KEY=
# ββ Deployed Contracts (auto-filled after deploy) ββ
MEMORY_ACCESS_CONTROL_ADDRESS=
AGENT_REGISTRY_ADDRESS=
# ββ Backend API βββββββββββββββββββββββββββββββββββββ
API_PORT=8000
SECRET_KEY=change-this-to-a-random-string# Compile Solidity contracts
npx hardhat compile
# Deploy to 0G Testnet
npm run deploy:testnet
# The deploy script will output contract addresses β
# update your .env with the printed addresses
# Seed the network with test agents and memories
npm run seed:testnetTerminal 1 β Backend API:
npm run backend
# or: cd backend && node server.jsTerminal 2 β Frontend Dashboard:
npm run frontend:dev
# or: cd frontend && npm run devOpen http://localhost:5173 in your browser to access the dashboard.
| Script | Command | Description |
|---|---|---|
| Compile Contracts | npm run compile |
Compile Solidity via Hardhat |
| Deploy to Testnet | npm run deploy:testnet |
Deploy contracts to 0G Testnet |
| Seed Testnet | npm run seed:testnet |
Inject test data on-chain |
| Start Backend | npm run backend |
Launch Express API server |
| Start Frontend | npm run frontend:dev |
Launch Vite dev server |
| Build Frontend | npm run frontend:build |
Create production bundle |
| Check SDK | npm run check:sdk |
Verify 0G SDK connectivity |
| Parameter | Value |
|---|---|
| Network Name | 0G Testnet |
| Chain ID | 16602 |
| RPC URL | https://evmrpc-testnet.0g.ai |
| EVM Target | shanghai |
| Block Explorer | chainscan-newton.0g.ai |
| Storage Indexer | https://indexer-storage-testnet-standard.0g.ai |
| Storage RPC | https://rpc-storage-testnet.0g.ai |
| Faucet | faucet.0g.ai |
AgentMemory ships with infrastructure-as-code config files for one-click deployment.
The backend serves the built frontend, so one Render service hosts the entire app.
- Push your code to GitHub
- Go to dashboard.render.com β New β Blueprint
- Connect your GitHub repo β Render auto-detects
render.yaml - Fill in the
PRIVATE_KEYenvironment variable when prompted - Click Apply β Render will build, deploy, and attach a persistent disk for SQLite
The
render.yamlblueprint handles:
- β Build:
npm installβfrontend buildβbackend install- β Start:
node server.js(serves API + static frontend)- β Health check at
/api/v1/health- β Persistent disk for SQLite database
- β All 0G environment variables pre-configured
If you want to host the frontend separately on Vercel:
- Go to vercel.com β Add New Project
- Import your GitHub repo
- Set Root Directory to
frontend - Vercel auto-detects
vercel.json(Vite framework) - Add environment variable:
VITE_API_URL= your Render backend URL (e.g.https://agentmemory.onrender.com) - Click Deploy
| Variable | Required | Where to Set | Description |
|---|---|---|---|
PRIVATE_KEY |
β | Render Dashboard | Your funded 0G testnet wallet private key |
OG_TESTNET_RPC_URL |
β | Auto-set by render.yaml |
https://evmrpc-testnet.0g.ai |
OG_TESTNET_CHAIN_ID |
β | Auto-set by render.yaml |
16602 |
OG_STORAGE_INDEXER_URL |
β | Auto-set by render.yaml |
0G Storage indexer endpoint |
OG_STORAGE_RPC_URL |
β | Auto-set by render.yaml |
0G Storage RPC endpoint |
MEMORY_ACCESS_CONTROL_ADDRESS |
β | Auto-set by render.yaml |
Deployed contract address |
AGENT_REGISTRY_ADDRESS |
β | Auto-set by render.yaml |
Deployed contract address |
SECRET_KEY |
β | Auto-generated by Render | API authentication secret |
VITE_API_URL |
β | Vercel (only for Option B) | Backend API URL |
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please ensure your code follows the existing style conventions and include tests where applicable.
This project is licensed under the MIT License β see the LICENSE file for details.
AgentMemory β Permanent memory for the autonomous future.
Built with β€οΈ on 0G Network
