MNEME — Portable Agent Memory

Portable · Monetisable · Cryptographically Verifiable AI Agent Memory

🌐 Live Demo  ·  Monad Explorer  ·  Contracts  ·  MCP Docs

---

MNEME is the only AI agent memory infrastructure with a built-in cryptographically verified Deletion Prover — allowing AI agents to persist knowledge across sessions while natively complying with GDPR Article 17 (Right to Erasure) via on-chain Monad tombstoning. Memory is portable. Raw memory content is not stored on-chain.

---

Hosted trust model

Memory content is encrypted at rest with AES-256-GCM. Vault keys are derived from the API server's ENCRYPTION_SECRET, not from a user-held encryption key. The API receives plaintext and decrypts memories during processing, so a hosted service operator can read them. This is not end-to-end encryption or a zero-knowledge service. Self-hosting gives you control of the API process and its secret, not protection from whoever administers that process. API keys authorize access; wallet identifiers and on-chain hashes do not stop the server from decrypting.

Read the trust model before storing sensitive data.

👥 Team

Name	Role
Hassan Rehman	Full-Stack & Blockchain Lead — REST API, Smart Contracts, MCP Integration, Hardhat, Monad Testnet Deployment
Mrunmayee Daware	Frontend & Compliance UI — Dashboard, GDPR Flows, Memory Market, Protocol & Infrastructure — Solidity Contracts

Contribution split

Contribution plan (50/50): Hassan Rehman focuses on the frontend, dashboard, and user-facing flows; Mrunmayee Daware focuses on the remaining software work, including backend/API, MCP, data and smart-contract integration, testing, and documentation.

---

📖 Table of Contents

• ✨ Features
• 🎥 Live Demo
• 🏗 Architecture
• 📂 Project Structure
• 📜 Smart Contracts
• 🔌 MCP Integration
• 🚀 Getting Started (Local)
• ☁️ Cloud Deployment (No Virtualization Needed)
• 🛠 Tech Stack
• 🛡 Security & Compliance

---

✨ Features

Feature	Description
🏛 Agent Vaults	Every AI agent gets a W3C DID-bound vault on Monad. Exportable memory with API-key access; hosted operators control encryption keys.
🔗 On-chain Attestations	Memory writes are hashed and recorded locally; when MONAD_RPC_URL, MONAD_PRIVATE_KEY and ATTESTATION_AGGREGATOR_ADDRESS are set, batches are submitted to AttestationAggregator.sol on Monad Testnet. The hosted demo API runs without them (see /v1/capabilities).
🗑 GDPR Deletion Prover	DeletionProver.sol records a SHA-256 deletion attestation and an on-chain tombstone for Article 17 erasure (not a zero-knowledge proof).
🧠 Semantic Recall	pgvector similarity search for natural-language memory retrieval.
🕰 Temporal Inspect	Query what an agent knew at any past timestamp — powerful for audits and debugging.
🛒 Memory Market	Agents list curated domain knowledge packs for USDC — 80% revenue to seller.
🔌 MCP Server	Drop-in integration with Claude Desktop, Cursor, Windsurf, and all MCP agents.
🏗 Offline-Resilient	Write path never blocks — Redis queues, Neo4j and extraction services degrade gracefully.
🔍 PII Scanning	All market submissions undergo regex PII scanning before listing.

---

🎥 Live Demo

Production URL: https://mneme-six.vercel.app

Click "⚡ Try Demo (no wallet needed)" on the landing page to instantly launch with pre-loaded demo data — no MetaMask or sign-up required.

---

🏗 Architecture

graph TD
    Agent["🤖 AI Agent"] -->|MCP Protocol| MCP["🔌 MCP Server"]
    User["👤 Operator"] -->|Web Browser| Web["🖥️ Next.js Dashboard"]
    MCP --> API
    Web --> API["⚡ Fastify REST API :3001"]

    API -->|Vectors and Metadata| PG[("🐘 PostgreSQL + pgvector")]
    API -.->|Offline Queue| Redis[("🔴 Redis")]
    API -.->|Fact Graph| Neo4j[("🕸️ Neo4j")]
    API -->|Raw text| Ext["🧠 Python Extraction"]
    Ext --> Neo4j

    API -->|Content hashes| AA["AttestationAggregator.sol"]
    API -->|Tombstone hashes| DP["DeletionProver.sol"]
    API -->|Vault DIDs| VR["VaultRegistry.sol"]
    MM["MemoryMarket.sol"] --> Monad

    AA --> Monad[("🟣 Monad Testnet chainId 10143")]
    DP --> Monad
    VR --> Monad

Loading

Memory Write Flow

Agent writes memory
  → API validates + computes SHA-256 content hash
  → PostgreSQL stores vector embedding + metadata
  → Redis queues async Neo4j entity extraction
  → AttestationAggregator.sol attests hash on Monad Testnet
  → Returns { memoryId, contentHash, monadTxHash }

GDPR Erasure Flow

Operator triggers erasure
  → API verifies operator owns vault
  → PostgreSQL rows permanently DELETED (data gone forever)
  → DeletionProver.sol records tombstoneHash on Monad (immutable)
  → Returns { tombstoneHash, monadTxHash, deletedCount }
  → Auditor: verifyDeletion(tombstoneHash) → true, zero PII exposed

---

📂 Project Structure

MNEME/
├── apps/
│   ├── api/                  # Fastify REST API (Node.js 22)
│   │   ├── src/routes/       # /vaults, /memories, /market, /compliance
│   │   ├── src/services/     # MemoryService, VaultService, MarketService
│   │   ├── src/db/           # Drizzle ORM + PostgreSQL + pgvector
│   │   └── src/blockchain/   # Monad Testnet contract clients (viem)
│   ├── extraction/           # Python FastAPI NLP extraction service
│   │   └── main.py           # SpaCy NER + entity graph writing to Neo4j
│   ├── mcp/                  # Model Context Protocol server (@mneme/mcp)
│   │   └── src/index.ts      # memory_write, memory_recall, memory_inspect tools
│   └── web/                  # Next.js 15 App Router dashboard
│       ├── src/app/          # Pages: landing, dashboard, memories, market, compliance, settings
│       ├── src/components/   # Design system: Button, Card, Badge, MonoHash
│       ├── src/lib/api.ts    # Typed API client with demo mode interceptor
│       └── src/store/        # Zustand auth store (persisted to localStorage)
├── contracts/                # Hardhat 2.x + Solidity 0.8.24
│   ├── contracts/
│   │   ├── core/
│   │   │   ├── VaultRegistry.sol          # DID to vault mapping
│   │   │   └── AttestationAggregator.sol  # Batch content hash attestation
│   │   ├── compliance/
│   │   │   └── DeletionProver.sol         # GDPR tombstone proof
│   │   └── market/
│   │       └── MemoryMarket.sol           # USDC memory pack marketplace
│   ├── scripts/              # deploy.ts, verify.ts
│   ├── test/                 # Hardhat + Chai unit tests
│   └── deployments/
│       ├── localhost-31337.json
│       └── monadTestnet-10143.json        # Live contract addresses
├── packages/
│   ├── sdk/                  # @mneme/sdk TypeScript client library
│   └── shared/               # Shared interfaces, Zod schemas, constants
├── docs/                     # Architecture diagrams, PRD, design specs
├── deploy/                   # Helm charts, CI/CD YAML
├── docker-compose.yml        # Local dev: Postgres, Redis, Neo4j
├── docker-compose.prod.yml   # Production hardened stack
└── vercel.json               # Vercel deployment config

---

📜 Smart Contracts

All contracts deployed on Monad Testnet (Chain ID: 10143, RPC: https://testnet-rpc.monad.xyz).

Deployed Addresses

Contract	Address	Explorer
VaultRegistry	0x19b31A7F2759Dac9FFe8Bf9C9D7e2C5446068b73	View ↗
AttestationAggregator	0x9c36aC707F29f0EfBb147710A288e3c9e4069A93	View ↗
MemoryMarket	0x0EE8903784a4f4974003548e0682d484849c7E27	View ↗
DeletionProver	0xF66260602E13e05EAcc56c238cD26587A3Cad9ea	View ↗
Mock USDC	0x6bbc2600813b109f78D61B2A78DCaFB1D6C1063E	View ↗

Deployer: 0x8e11d906a07F037029409e21fa14A0B733F0B431 Deployed: 2026-07-04T08:12:17Z Network: Monad Testnet · Chain ID 10143 · EVM version cancun

Contract Details

VaultRegistry.sol

• Maps W3C DIDs (did:monad:testnet:<address>) to on-chain vault records
• Functions: registerVault(), destroyVault(), getVault(), operatorVaults()
• Events: VaultRegistered, VaultDestroyed
• Uses: OpenZeppelin v5 Ownable, ReentrancyGuard, ECDSA, MessageHashUtils

AttestationAggregator.sol

• Stores batched SHA-256 fingerprints of memory operations — raw content never stored on-chain
• Operations tracked: WRITE, UPDATE, DELETE, EXPORT
• Functions: submitBatch(), getAttestation(), verifyAttestation()
• Events: BatchSubmitted, AttestationVerified
• Gas-optimised: batch submission reduces per-memory gas cost ~90%

DeletionProver.sol

• GDPR Article 17 tombstone registry — immutable proof of data erasure
• Record fields: tombstoneHash, deletedHashes[], gdprBasis, userIdentifier (anonymised), blockNumber
• Functions: proveDeletion(), verifyDeletion(), getVaultDeletions()
• Auditors verify deletion without PII: verifyDeletion(tombstoneHash) → true

MemoryMarket.sol

• Peer-to-peer marketplace for packaged AI agent domain knowledge
• Revenue: 80% seller / 20% platform in USDC (ERC-20)
• Functions: listPack(), purchasePack(), delistPack(), withdrawRevenue()
• Events: PackListed, PackPurchased, PackDelisted
• 48-hour timelock on treasury changes, ReentrancyGuard on all financial functions

Working with Contracts

# Compile
npm run compile --workspace=contracts

# Test
npm test --workspace=contracts

# Deploy to Monad Testnet
MONAD_PRIVATE_KEY=0x... npx hardhat run scripts/deploy.ts --network monadTestnet --prefix=contracts/

# Start local Hardhat node
npm run node --workspace=contracts

---

🔌 MCP Integration

MNEME ships a Model Context Protocol server (apps/mcp/) — drop-in integration with any MCP-compatible AI agent.

Available MCP Tools

memory_write, memory_recall, memory_forget, memory_inspect, memory_export, memory_import, and memory_list.

Remote setup: Cursor and Windsurf Cascade

The API serves Streamable HTTP at /mcp. After deploying the updated API, use this config in Cursor's mcp.json or Windsurf Cascade's ~/.codeium/windsurf/mcp_config.json. Use your real vault UUID, not a vlt_ demo ID.

{
  "mcpServers": {
    "mneme-memory": {
      "url": "https://trymneme-api.onrender.com/mcp?vault=YOUR_VAULT_UUID",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Claude Desktop: local server

@mneme/mcp is not published on npm. Build from this repository instead:

git clone https://github.com/h55n/MNEME.git
cd MNEME
npm ci
npm run build --workspace=packages/shared
npm run build --workspace=apps/mcp

In Claude Desktop's claude_desktop_config.json, replace the absolute path:

{
  "mcpServers": {
    "mneme-memory": {
      "command": "node",
      "args": ["/absolute/path/MNEME/apps/mcp/dist/index.js"],
      "env": {
        "MNEME_API_URL": "https://trymneme-api.onrender.com/v1",
        "MNEME_API_KEY": "YOUR_API_KEY",
        "MNEME_VAULT_ID": "YOUR_VAULT_UUID"
      }
    }
  }
}

Restart the app and allow the tools you need. The same local server can be used in Cursor and Windsurf. Keep API keys out of shared configs and source control.

Claude remote connectors can use the endpoint above only where the request-header beta is available. ChatGPT's custom MCP apps have separate plan/auth requirements; MNEME does not yet implement OAuth. Do not make a private vault endpoint public to bypass that requirement. See client setup and validation for exact limits, plugin-style options, and the test matrix.

SDK Usage

import { MnemeClient } from '@mneme/sdk';

const client = new MnemeClient({
  apiUrl: 'https://mneme-six.vercel.app/api/v1',
  apiKey: 'mnk_live_your-api-key',
  vaultId: 'vlt_your-vault-id',
});

// Write
const mem = await client.memories.write({
  content: 'User prefers TypeScript strict mode',
  type: 'procedural',
  tags: ['coding', 'typescript'],
  importance: 0.8,
});

// Recall
const hits = await client.memories.recall('TypeScript preferences');

// Temporal snapshot
const snapshot = await client.memories.inspect({
  timestamp: '2026-01-01T00:00:00Z',
});

---

🚀 Getting Started (Local)

Prerequisites

• Node.js >= 22.x
• Docker & Docker Compose (Postgres, Redis, Neo4j) — Requires Virtualization enabled in BIOS/OS.
• Python >= 3.11 (extraction service only)

1. Clone & Configure

git clone https://github.com/h55n/MNEME.git
cd MNEME
cp .env.example .env
# Fill in: POSTGRES_PASSWORD, REDIS_PASSWORD, MONAD_PRIVATE_KEY, etc.

2. Start Infrastructure

docker-compose up -d
# PostgreSQL 16 + pgvector, Redis 7, Neo4j 5

3. Install & Bootstrap

npm install
npm run db:push --workspace=apps/api

4. Run Dev Stack

npm run dev
# Fastify API :3001 + Next.js Dashboard :3000 + Python Extraction :8000

Tip

The dashboard runs in Demo Mode when no backend is reachable. All features work with realistic mock data — no MetaMask required.

---

☁️ Cloud Deployment (No Virtualization Needed)

If your machine does not support virtualization (Docker Desktop fails to start), you can deploy MNEME directly to the cloud without local containers.

1. Managed Databases

Create free tiers of the following services and add their connection strings to your .env:

• Neon Serverless Postgres: Provides PostgreSQL 16 + pgvector. Set DATABASE_URL.
• Upstash Redis: Serverless Redis. Set REDIS_URL.
• AuraDB (Optional): Managed Neo4j graph database. Set NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD.

2. Deploy Backend to Render

1. Create a Render account and connect your GitHub repository.
2. Render will automatically detect the render.yaml blueprint included in the root of this project.
3. Apply the blueprint to spin up both the Node API and the Python Extraction Service.
4. Configure your .env variables in the Render dashboard.

3. Deploy Frontend to Vercel

1. Run npx vercel or connect the repo to Vercel.
2. Set NEXT_PUBLIC_API_URL to your Render API deployment URL (e.g., https://mneme-api-xxx.onrender.com/v1).
3. Vercel will automatically read the vercel.json config and deploy the Next.js app.

---

🛠 Tech Stack

Frontend

Technology	Version	Purpose
Next.js	15.5.27	App Router, SSG, RSC
React	18.x	UI rendering
TypeScript	5.x	Type safety
Zustand	4.x	Auth state (persisted)
TanStack Query	5.x	Server state, caching
Sonner	1.x	Toast notifications
Lucide React	Latest	Icons

Backend

Technology	Version	Purpose
Fastify	5.x	REST API
Drizzle ORM	Latest	Type-safe PostgreSQL
PostgreSQL + pgvector	16	Vector + metadata storage
Redis	7.x	Write queue + caching
Neo4j	5.x	Semantic entity graph
Python FastAPI	Latest	NLP extraction microservice
SpaCy	3.x	Named Entity Recognition
viem	2.x	Monad Testnet contract client
Turborepo	2.x	Monorepo orchestration

Blockchain

Technology	Version	Purpose
Solidity	0.8.24	Smart contract language
Hardhat	2.x	EVM development framework
OpenZeppelin	5.x	Ownable, ReentrancyGuard, ECDSA
Monad Testnet	ChainID 10143	Parallel EVM L1
EVM version	cancun	Latest opcodes, viaIR optimiser

Infrastructure

Technology	Purpose
Vercel	Frontend hosting (Edge CDN)
Docker Compose	Local dev + production containers
GitHub Actions	CI/CD pipeline
Turborepo Remote Cache	Build caching

---

🛡 Security & Compliance

• Attestation: Every memory_write produces a SHA-256 content hash. With chain settings configured, batches are attested on Monad; without them (the hosted demo), attestations stay local records. /v1/capabilities reports which mode is active.
• GDPR Art. 17: DeletionProver.sol tombstones allow verifying deletion with zero PII exposure
• Vault identity: DIDs and wallet identifiers do not provide end-to-end content encryption; the API holds the server secret that derives memory keys.
• ReentrancyGuard: All financial functions in MemoryMarket.sol
• 48-hour timelock: Treasury parameter changes in MemoryMarket.sol
• ECDSA verification: Operator signature checks on all vault operations
• PII scanning: Regex pass required before market pack listing
• Known limitation: POST /market/packs/scan receives plaintext. The operator decrypts memories locally and sends the content to the API for PII scanning; the API does not store it. Scanning encrypted content server-side is not implemented.

Warning

Set strong passwords for POSTGRES_PASSWORD, REDIS_PASSWORD, NEO4J_AUTH in .env before running docker-compose.prod.yml.

Caution

Never commit MONAD_PRIVATE_KEY to Git. The .gitignore excludes .env but always verify before pushing.

---

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📄 License

MIT — see LICENSE for details.

---

Built with ❤️ by Hassan Rehman and Mrunmayee Daware

Powered by Monad — the parallel EVM L1

Free demo liveness

The /livez route checks only that the API process can answer HTTP. It does not query PostgreSQL or verify memory operations. The demo-liveness workflow requests it every ten minutes, best effort, without repository secrets. Its job is disabled unless the repository variable KEEPALIVE_ENABLED is set to true; enable that only after /livez has been deployed and verified. GitHub can delay/drop runs or disable schedules after 60 inactive days, and Render can restart free instances. This reduces idle sleeps; it does not provide an uptime or latency guarantee. Render free instance-hours are shared across the workspace. Database inactivity shutdown is not defeated by this workflow. Use /health for manual dependency diagnosis, not scheduled keep-alive traffic.