@manifesto-ai/memory

Memory is the retrieval layer for past World/Snapshot information in Manifesto.

What is Memory?

Memory provides a 4-Layer Architecture for searching and using past World information. It operates as an optional layer between Actors and World Protocol.

In the Manifesto architecture:

Actor ──→ MEMORY ──→ World Protocol
              │
     Retrieves past Worlds
     Traces selection decisions

What Memory Does

| Responsibility | Description | |----------------|-------------| | Store | Persist and retrieve World objects | | Verify | Pure function verification of World existence/integrity | | Select | Find relevant past Worlds based on queries | | Trace | Record selection decisions for accountability |

What Memory Does NOT Do

| NOT Responsible For | Who Is | |--------------------|--------| | Execute effects | Host | | Apply patches | Host | | Make governance decisions | World | | Compute state transitions | Core |

Installation

npm install @manifesto-ai/memory
# or
pnpm add @manifesto-ai/memory

Peer Dependencies

npm install @manifesto-ai/world  # Required peer

Quick Example

import {
  InMemoryStore,
  createExistenceVerifier,
  createSimpleSelector,
  createMemoryTrace,
  attachToProposal,
} from "@manifesto-ai/memory";
import type { ActorRef } from "@manifesto-ai/world";

// Setup
const store = new InMemoryStore();
const verifier = createExistenceVerifier();
const selector = createSimpleSelector(store, verifier);

// Index a World
store.put(world);
selector.addToIndex(world.worldId, ["keyword1", "keyword2"], world.createdAt);

// Select relevant memories
const actor: ActorRef = { actorId: "agent-1", kind: "agent" };
const result = await selector.select({
  query: "keyword1",
  atWorldId: currentWorld.worldId,
  selector: actor,
  constraints: { maxResults: 5, minConfidence: 0.7 },
});

// Create trace and attach to proposal
const trace = createMemoryTrace(
  actor,
  "keyword1",
  currentWorld.worldId,
  result.selected
);
const proposalWithMemory = attachToProposal(proposal, trace);

See GUIDE.md for the full tutorial.

Core Concepts

Memory ≠ Truth

Memory is a reference to past Worlds, not the truth itself. The referenced World is the source of truth.

Selection is Non-deterministic but Traced

Memory selection may involve LLM-based ranking or other non-deterministic processes. However, every selection MUST be recorded in a MemoryTrace for accountability.

Verifier MUST be Pure

Verifiers are pure functions with no side effects:

• No Store access
• No IO (network, filesystem)
• No Date.now()
• Same inputs always produce same outputs

API Overview

Interfaces

// Store - Persists and retrieves Worlds
interface MemoryStore {
  get(worldId: WorldId): Promise<World | null>;
  exists(worldId: WorldId): Promise<boolean>;
}

// Verifier - Pure function verification (M-8)
interface MemoryVerifier {
  prove(memory: MemoryRef, world: World): ProveResult;
  verifyProof(proof: VerificationProof): boolean;
}

// Selector - Finds relevant past Worlds
interface MemorySelector {
  select(request: SelectionRequest): Promise<SelectionResult>;
}

Trace Utilities

function createMemoryTrace(
  selector: ActorRef,
  query: string,
  atWorldId: WorldId,
  selected: SelectedMemory[]
): MemoryTrace;

function attachToProposal<P extends Proposal>(
  proposal: P,
  trace: MemoryTrace
): P;

function getFromProposal(proposal: Proposal): MemoryTrace | undefined;

// M-12: Extract proof for Authority verification
function extractProof(evidence: VerificationEvidence): VerificationProof;

Verifier Implementations

| Verifier | Complexity | Security | Use Case | |----------|------------|----------|----------| | ExistenceVerifier | Low | Low | Development/testing | | HashVerifier | Medium | Medium | General production | | MerkleVerifier | High | High | Audit compliance |

See SPEC.md for complete API reference.

Relationship with Other Packages

┌─────────────┐
│    Actor    │ ← Uses Memory to reference past Worlds
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   MEMORY    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│    World    │ ← Memory depends on World types
└─────────────┘

| Relationship | Package | How | |--------------|---------|-----| | Depends on | @manifesto-ai/world | Uses WorldId, World, ActorRef, Proposal types | | Used by | Actor implementations | Actors use Memory to reference past decisions |

Module Boundaries (SPEC §9)

| Module | Store | prove() | verifyProof() | Selector | |--------|-------|---------|---------------|----------| | Actor | ✅ | ✅ | ✅ | ✅ | | Projection | ❌ | ❌ | ❌ | ❌ | | Authority | ❌ | ❌ | ✅ | ❌ | | Host | ❌ | ❌ | ❌ | ❌ | | Core | ❌ | ❌ | ❌ | ❌ |

When to Use Memory Directly

Most applications don't need Memory.

Use Memory directly when:

• Referencing past World states for decision-making
• Tracking decision rationale with verifiable evidence
• Audit compliance requiring proof of past state access
• Building AI agents that need historical context

Documentation

| Document | Purpose | |----------|---------| | GUIDE.md | Step-by-step usage guide | | SPEC.md | Complete specification | | FDR.md | Design rationale | | USAGE.md | World integration guide |

License

MIT