DeMem

DeMem is a decentralized long-term memory layer for AI agents.

This repository is a practical MVP you can commit to GitHub today. It gives you:

• an API for ingesting and querying agent memories
• append-only cryptographic receipts for every stored memory
• a verification endpoint to prove the receipt chain has not been tampered with
• a local object store that works immediately
• optional Shelby storage and optional Aptos anchoring adapters

What this MVP does

When an agent writes a new memory, DeMem:

1. normalizes the memory into a canonical JSON record
2. stores the raw memory as a blob
3. computes a contentHash
4. creates a chained receipt with previousReceiptHash
5. anchors that receipt using either:
   • local anchor mode for development
   • aptos anchor mode for real on-chain anchoring
6. stores searchable metadata in a lightweight per-agent catalog

This gives you a clean starting point for:

• AI agent memory persistence
• verifiable history and audit trails
• agent ownership and future memory-tokenization experiments
• upgrading later to embeddings, reranking, and on-chain provenance

Architecture

Agent / App
   |
   v
DeMem API
   |
   +--> Object Store
   |      - Local filesystem (works now)
   |      - Shelby adapter (optional)
   |
   +--> Receipt Service
   |      - content hash
   |      - append-only receipt hash chain
   |
   +--> Anchor Store
          - Local mock anchor
          - Aptos anchor adapter (optional)

Tech choices

This MVP intentionally stays simple:

• TypeScript backend
• zero mandatory runtime dependencies for the core local mode
• JSON blob storage for raw memory
• receipt hash chain for verifiable history
• lexical + vector-ready query layer

That means you can run it immediately, then progressively replace parts later with:

• Shelby for blob storage
• Aptos Move module for anchoring
• pgvector / Qdrant / Milvus for semantic retrieval
• Redis / Kafka for event-driven ingestion

Project structure

src/
  app.ts                     # service wiring
  server.ts                  # HTTP server
  config.ts                  # env loading
  routes/
    agent-routes.ts          # API routing
  services/
    memory-service.ts        # ingest + load memories
    query-service.ts         # retrieval logic
    receipt-service.ts       # receipt creation + chain verification
    verification-service.ts  # verify an agent's receipt chain
  stores/
    object-store.ts
    local-object-store.ts
    shelby-object-store.ts
    anchor-store.ts
    local-anchor-store.ts
    aptos-anchor-store.ts
    catalog-store.ts
  types/
    domain.ts
  utils/
    crypto.ts
    text.ts

tests/
  receipt-service.test.ts
  query-service.test.ts

Quick start

1. Clone and enter the repo

git clone <your-repo-url>
cd demem

2. Create your env file

cp .env.example .env

3. Build

npm install
npm run build

4. Start

npm start

The API will run on:

http://127.0.0.1:3000

Development mode

If you want to run TypeScript directly:

npm run start:ts

Core environment variables

APP_PORT=3000
APP_HOST=0.0.0.0
DATA_DIR=./data

OBJECT_STORE_DRIVER=local
ANCHOR_DRIVER=local

Shelby mode

To switch raw memory storage from local files to Shelby:

OBJECT_STORE_DRIVER=shelby
SHELBY_NETWORK=testnet
SHELBY_API_KEY=...
SHELBY_PRIVATE_KEY=ed25519-priv-...
SHELBY_ACCOUNT_ADDRESS=0x...
SHELBY_RPC_BASE_URL=https://api.testnet.shelby.xyz/shelby
SHELBY_BLOB_EXPIRATION_DAYS=30

Extra packages for Shelby mode

npm install @shelby-protocol/sdk @aptos-labs/ts-sdk

Aptos anchor mode

To anchor receipts on Aptos:

ANCHOR_DRIVER=aptos
APTOS_NETWORK=TESTNET
APTOS_PRIVATE_KEY=ed25519-priv-...
APTOS_MODULE_FUNCTION=0xYOUR_MODULE::demem_anchor::anchor_receipt

Extra packages for Aptos mode

npm install @aptos-labs/ts-sdk

API

Health check

GET /health

Ingest a memory

POST /v1/agents/:agentId/memories
Content-Type: application/json

Example:

{
  "kind": "fact",
  "text": "User prefers decentralized storage with verifiable receipts.",
  "tags": ["memory", "audit"],
  "sessionId": "session-001",
  "source": "agent-runtime"
}

List memories

GET /v1/agents/:agentId/memories

Get one memory

GET /v1/agents/:agentId/memories/:memoryId

Query memories

POST /v1/agents/:agentId/query
Content-Type: application/json

Example lexical query:

{
  "query": "decentralized memory receipts",
  "topK": 5,
  "includeRaw": true
}

Example vector-ready query:

{
  "embedding": [0.12, -0.08, 0.55, 0.91],
  "topK": 10,
  "includeRaw": true
}

List receipts

GET /v1/agents/:agentId/receipts

Get receipt for one memory

GET /v1/agents/:agentId/receipts/:memoryId

Verify receipt chain

GET /v1/agents/:agentId/verify

Example curl flow

Write a memory

curl -X POST http://127.0.0.1:3000/v1/agents/agent-123/memories \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "fact",
    "text": "User wants decentralized AI memory with receipts",
    "tags": ["memory", "audit"]
  }'

Query it back

curl -X POST http://127.0.0.1:3000/v1/agents/agent-123/query \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "decentralized memory receipts",
    "includeRaw": true
  }'

Verify the receipt chain

curl http://127.0.0.1:3000/v1/agents/agent-123/verify

Local persistence

By default, raw memories and catalog metadata are stored under:

data/
  blobs/
  catalog/
  anchor-log.ndjson

This is good for local development and demos.

What is real vs placeholder right now

Fully working now

• local blob storage
• memory ingest
• memory retrieval
• lexical query
• vector-ready scoring if embeddings are supplied
• append-only receipt chain
• local anchor log
• chain verification endpoint
• test coverage for receipt verification and ranking behavior

Optional integrations already scaffolded

• Shelby object store adapter
• Aptos transaction-based anchor adapter

Not included yet

• automatic embedding generation
• per-tenant auth / API keys
• rate limiting
• encryption at rest
• RBAC / ACLs
• Move smart contract in this repo
• background compaction / summarization
• distributed index layer

Suggested next steps

Phase 1

• add API key auth
• add tenants / namespaces
• add memory deletion tombstones instead of hard delete
• add summarization jobs

Phase 2

• plug in OpenAI or local embedding generation
• store embedding vectors in pgvector or Qdrant
• add hybrid retrieval + reranking

Phase 3

• deploy a real Aptos module for anchoring
• expose anchor explorer links
• add signed ownership / transfer mechanics for memory assets

Tests

npm test

Git init and first commit

git init
git add .
git commit -m "feat: initial DeMem MVP with verifiable memory receipts"

Important note

This repository is an MVP foundation, not a finished production memory network. Its value is that it already encodes the core model of DeMem:

• raw memory blobs
• searchable metadata
• append-only receipt history
• optional decentralized storage
• optional on-chain anchoring

That is enough to demo, iterate, pitch, and start integrating with real AI agents.