Memory Schema

# People (relationship module)
danno, alice, team-engineering

# Projects / work
q2-review, mnemos-launch, client-acme

# Time
weekly, monthly, 2026-q1

# Status / action
follow-up, in-progress, completed, blocked, archived

/** Categories map to the six MNEMOS product modules */
export type MemoryCategory =
  | "relationship"  // MODULE_02
  | "goal"          // MODULE_03
  | "decision"      // MODULE_04
  | "health"        // MODULE_05
  | "context"       // MODULE_01 — general second-brain context
  | "api";          // MODULE_06 — third-party API writes

/** Raw storage record (server-side, contains ciphertext) */
export interface MemoryStreamContent {
  ciphertext:    string;           // AES-256-GCM blob: base64url(iv) + "." + base64url(ct)
  walletAddress: string;           // owner wallet (lowercase)
  category:      MemoryCategory;
  tags:          string[];         // unencrypted, used for filtering
  title?:        string;           // AI-generated, stored unencrypted
  createdAt:     string;           // ISO timestamp
  updatedAt:     string;           // ISO timestamp
  deletedAt?:    string;           // set on soft delete
  vaultId?:      string;           // shared vault FK — undefined for personal memories
}

/** Hydrated record returned by the API (post-decrypt on client) */
export interface MemoryRecord {
  streamId:      string;           // "mem_" + nanoid(8)
  content?:      string;           // decrypted plaintext — only after client-side decrypt
  title?:        string;           // AI-generated title (always present if enriched)
  walletAddress: string;
  category:      MemoryCategory;
  tags:          string[];
  createdAt:     string;
  updatedAt:     string;
  deletedAt?:    string;
  ciphertext:    string;           // always present — raw encrypted blob
  vaultId?:      string;
}

Format: base64url(iv[12 bytes]) + "." + base64url(AES-GCM ciphertext)

Example:
  "aBcD1234EFGH.xYz9876uvWXabcdef..."
   ^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^
   12-byte IV    encrypted content + 16-byte GCM auth tag

Properties:
  - New random 96-bit IV per write → same plaintext never produces same ciphertext
  - GCM auth tag: any tampering causes decryption to throw (integrity guarantee)
  - base64url encoding: URL-safe, no padding

export interface SharedVault {
  id:           string;
  name:         string;
  ownerWallet:  string;
  createdAt:    string;
  updatedAt:    string;
  members?:     VaultMember[];
}

export interface VaultMember {
  vaultId:          string;
  walletAddress:    string;
  role:             "owner" | "writer" | "viewer";
  wrappedVaultKey:  string;  // AES-GCM wrapped vault key: base64url(iv).base64url(wrapped)
  ephemeralPubkey:  string;  // SPKI base64url P-256 public key used during wrapping
  joinedAt:         string;
}

export interface VaultInvite {
  id:               string;
  vaultId:          string;
  inviteeWallet:    string;
  role:             "owner" | "writer" | "viewer";
  wrappedVaultKey:  string;
  ephemeralPubkey:  string;
  status:           "pending" | "accepted" | "declined" | "revoked";
  createdAt:        string;
  expiresAt?:       string;
}

export interface SessionMemory {
  id:        string;
  title?:    string;
  content:   string;    // decrypted plaintext — only in session cache
  category:  string;
  tags:      string[];
  createdAt: string;
}

export interface SessionData {
  walletAddress: string;
  memories:      SessionMemory[];
  syncedAt:      string;
  expiresAt:     string;   // 60 minutes from sync time
}