Kinetics

inetics is a TypeScript-first protocol and app stack for:

- portable private agent memory
- creator-owned skill packs
- licensed agent capabilities on 0G

It gives a user a vault that can be written by one client and recalled by another compatible MCP-connected agent, while also enabling a public marketplace for monetizable skill packs.

## Problem

AI agents today are fragmented.

- Private memory is usually trapped inside one app, one backend, or one session.
- Users cannot carry their memory layer across tools.
- Agent skills are hard to package, license, and distribute cleanly.
- Most systems optimize for app retention, not user ownership.

This creates two core gaps:

1. users do not own a portable memory identity
2. creators do not have a native marketplace for reusable agent capabilities

## Solution

Kinetics splits the system into two product surfaces:

- `Private Memory Pass`
  - a user buys a pass
  - derives a vault key
  - writes encrypted memory to 0G-backed storage
  - syncs the vault across compatible clients and MCP agents

- `Skill Pack Marketplace`
  - a creator publishes a pack and new versions
  - a buyer purchases a timed license
  - the creator issues an access grant
  - the buyer mounts the licensed pack into an agent workflow

## Why 0G

Kinetics uses 0G because the product needs all of these at once:

- verifiable data availability for memory and pack artifacts
- on-chain entitlements for passes and licenses
- user-portable state pointers instead of app-local storage only
- a design that works for both frontend clients and MCP agents

## Core Ideas

- encrypted private memory belongs to the user, not the app
- memory writes should be fast enough for real agent workflows
- sync should be explicit when cross-client sharing is needed
- creator assets should be publishable as reusable packs
- buyer access should be controlled by time-bounded licenses and grants

## Architecture

```mermaid
flowchart LR
  U[User Wallet] --> W[Web App]
  U --> M[MCP Client]

  W --> C[@kinetics/core]
  M --> S[@kinetics/mcp-server]
  S --> C

  C --> A[@kinetics/abi]
  C --> ZS[0G Storage]
  C --> ZC[0G Chain]

  ZC --> MP[MemoryPass]
  ZC --> MR[MemoryRegistry]
  ZC --> KP[KnowledgePackNFT]
  ZC --> PL[PackLicenseRegistry]
```

## Memory Flow

```mermaid
sequenceDiagram
  participant User
  participant ClientA as Writer Client / Codex
  participant Core as @kinetics/core
  participant Storage as 0G Storage
  participant Chain as 0G Chain
  participant ClientB as Reader Client / Claude

  User->>ClientA: Buy Memory Pass
  ClientA->>Chain: buyPass(planId)
  User->>ClientA: Add private memory
  ClientA->>Core: memory_add(...)
  Core->>Storage: upload encrypted blob
  Core->>Chain: updateRoot(...)
  ClientA->>Core: memory_push_index()
  Core->>Storage: upload encrypted snapshot
  Core->>Chain: setLatestIndex(...)
  ClientB->>Core: memory_pull_index()
  Core->>Storage: fetch latest snapshot
  ClientB->>Core: memory_query(...)
```

## Marketplace Flow

```mermaid
sequenceDiagram
  participant Creator
  participant Buyer
  participant Core as @kinetics/core
  participant Storage as 0G Storage
  participant Chain as 0G Chain

  Creator->>Core: skill_publish(draft)
  Core->>Storage: upload preview + bundle
  Core->>Chain: mint pack and publish version

  Buyer->>Core: skill_search() / skill_get()
  Buyer->>Core: skill_buy(packId)
  Core->>Chain: buyLicense(...)

  Creator->>Core: skill_publish_access_grant(...)
  Core->>Storage: upload buyer grant artifact
  Core->>Chain: publishAccessGrant(...)

  Buyer->>Core: skill_mount(packId)
  Core->>Storage: fetch granted manifest + bundle
```

## 0G Integration

Kinetics uses 0G in four places.

### 1. Contract Layer

Deployed contracts define the ownership and entitlement model.

- `MemoryPass`
  - buy, renew, and upgrade vault access
  - stores the latest canonical index pointer
- `MemoryRegistry`
  - append-only Merkle root history for memory proofs
- `KnowledgePackNFT`
  - creator-owned pack identity and version metadata
- `PackLicenseRegistry`
  - timed buyer licenses and access grant publication

### 2. Storage Layer

0G Storage is used for:

- encrypted memory blobs
- encrypted vault snapshots
- preview manifests
- licensed pack bundles
- buyer access grants

### 3. Shared SDK Layer

`@kinetics/core` wraps the actual 0G interactions:

- upload / download
- encryption / decryption
- vault sync
- contract clients
- pack publish / mount logic

### 4. Client Layer

Both the web app and MCP server use the same shared business logic, which keeps behavior consistent across UI and agent flows.