Vermory

Governed Memory for AI

Chinese documentation

Vermory is a reality-first memory and context continuity platform for AI clients. It is designed for coding agents, web chat, assistants, and other tools that need to continue real work without mixing unrelated projects, reviving stale facts, or turning every conversation into permanent memory.

Vermory is more than a memo store. Its core problem is deciding:

• which continuity the current interaction belongs to;
• which observations deserve durable memory;
• which source is authoritative when facts conflict;
• which facts are current, superseded, local, global, or deleted;
• what context a specific AI task should receive;
• how every formation, correction, recall, bridge, and deletion remains explainable.

Continuity Model

Vermory organizes continuity by anchor strength rather than by arbitrary content categories.

Mode	Anchor	Expected behavior
Workspace-backed continuity	Repository root, workspace path, manifest, explicit workspace binding	The same workspace can continue across supported coding clients; different workspaces remain isolated.
Conversation-backed continuity	Thread, channel, contact, named matter, explicit topic	Everyday matters can continue across conversations without merging unrelated topics.
Global Defaults	Explicit stable user preferences and long-lived settings	A deliberately thin layer; temporary task instructions must not silently become permanent defaults.

Cross-mode operations such as promote, link, export, adopt, and rebind are governed bridge actions, not implicit mixing.

Product Invariants

The current constitution requires:

• zero forbidden cross-tenant and cross-continuity leakage in labeled hard-gate cases;
• no automatic strong-anchor merge when binding is ambiguous;
• no stale or superseded fact represented as current;
• no deleted target returned through exact, paraphrased, semantic, cached, historical, or adapter-backed recall;
• live repository and source reality can correct stale descriptive memory;
• model inference cannot silently override explicit user intent;
• PostgreSQL remains authoritative while search projections stay disposable and rebuildable;
• mem0, MemOS, Supermemory, and future systems remain optional projection adapters rather than second sources of truth.

See the Product Constitution.

Current Status

Vermory is in evidence-driven development.

Experiment 0 is complete. It provides:

• a strict reality-case manifest and JSONL event contract;
• source authorization, anonymization, fixture hashing, and path containment checks;
• deterministic fixture-lock.json generation and mutation detection;
• public and withheld_local evidence levels without fake local sealing;
• Ed25519 verification for attestations received from an external sealed evaluator;
• four frozen first-batch cases covering workspace continuity, conversation continuity, Global Defaults, deletion, and source injection;
• JSON and Markdown Experiment 0 reports.

The current pass=true result means the first evidence batch is valid and frozen. It does not mean a complete production memory engine has already passed those cases. Experiment 1 is responsible for executing the frozen trajectories through a production-shaped memory slice and real AI clients.

Read the Experiment 0 report.

Architecture Direction

flowchart LR
    Client["AI client or harness"] --> Resolve["Continuity resolution"]
    Resolve --> Govern["Formation and governance"]
    Govern --> PG["Authoritative PostgreSQL state"]
    PG --> Project["Rebuildable search projections"]
    Project --> Compose["Task-aware context composition"]
    Compose --> Client
    Client --> Observe["Post-task observations"]
    Observe --> Govern

Loading

The final physical schema, memory taxonomy, lifecycle names, ranking algorithm, API shape, SLOs, and scale profile are intentionally not frozen yet. They remain falsifiable hypotheses until real trajectories discriminate them.

Quick Start

Requirements:

• Go 1.25.7 or a compatible newer toolchain;
• jq for inspecting generated evidence;
• PostgreSQL only for commands that exercise the native backend or legacy vertical slice.

Run the test suite:

go test ./...
go test -race ./internal/reality
go vet ./...

Inspect the CLI:

go run ./cmd/vermory --help

Validate the frozen public cases:

go run ./cmd/vermory reality-validate \
  --case-root reality/cases \
  --artifact-root ./artifacts \
  --run-id experiment-0-public-v1

Generate the Experiment 0 readout:

go run ./cmd/vermory experiment-0 \
  --case-root reality/cases \
  --artifact-root ./artifacts \
  --run-id experiment-0-v1

Generated artifacts are written below artifacts/ and are intentionally not committed.

Repository Layout

cmd/vermory/              CLI entry point
internal/reality/         Reality evidence, freeze, validation, attestation, readout
reality/cases/            Frozen public reality trajectories
reality/schema/           Machine-readable case and attestation schemas
internal/memorybackend/   Native and optional retrieval projection adapters
internal/resolver/        Workspace, conversation, and Global Defaults resolution
internal/governance/      Existing governed-claim vertical-slice services
internal/bridge/          Promote, link, export, adopt, and rebind primitives
casebook/                 Historical ContextMesh compatibility harness
docs/                     Constitution, Reality Program, ADRs, evidence, and plans

Historical ContextMesh case IDs, artifact names, and database identifiers remain stable evidence identifiers unless an explicit migration changes them.

Evidence-First Development

New permanent architecture should follow this order:

real failure or trajectory
-> frozen current and forbidden behavior
-> public and withheld evaluation evidence
-> comparable baselines
-> implementation hypothesis
-> real client execution
-> failure, deletion, migration, and scale verification

Do not add a new schema entity, service, lifecycle state, provider dependency, or release metric only because it appears architecturally complete. Map it to a falsifiable hypothesis and a real case first.

Backend Decision

The current native deployment decision is PostgreSQL plus pgvector. Existing backend evidence also covers mem0, MemOS, and Supermemory adapters.

The backend bake-off proves the tested retrieval and lifecycle adapter contract only. It does not prove end-to-end formation, continuity resolution, context utility, real-client integration, or sealed quality.

See Backend Bake-Off Results.

Contributing

Read CONTRIBUTING.md before submitting code or evidence. Reality cases must never include credentials, private raw transcripts, unredacted personal paths, or a false sealed label.

Security reports should follow SECURITY.md.

License

Licensed under the Apache License 2.0.