Capsule Memory Kit

A clean, provider-neutral memory capsule template for local agents.

The repository contains the mechanism only: file layout, startup contract, demand-intake gate, generated runtime packs, local search index, privacy audit, and maintenance commands. It intentionally does not contain a real user's memories, preferences, project notes, private paths, session logs, credentials, or vendor-specific operating assumptions.

Use it when you want a private memory capsule that any file-reading agent can understand.

One Instruction For An Agent

Give an agent this instruction after cloning the repository:

Use this repository as a portable memory capsule template. Read README.md and AGENTS.md, initialize a private capsule with the quick-start command, and before acting on nontrivial or fuzzy requests run the intake gate to clarify goal, source boundary, research gate, action gate, and acceptance checks. Store real user memory only in the user's private capsule, never in this public template.

Why This Exists

Long-running agent work needs memory, but memory creates three failure modes:

• chat-history lock-in: useful context is trapped in one product or thread;
• startup bloat: loading everything upfront makes the first prompt unstable and expensive;
• silent drift: new preferences or source-of-truth claims can conflict with older memory.

Capsule Memory Kit handles those problems with a small filesystem contract. Agents read a stable startup surface, retrieve detailed memory only after the task is known, write durable updates through a scripted command, and fail validation when conflicts or private data appear.

What Is Public Here

This repository is safe to keep public because it contains only:

• generic scripts;
• generic templates;
• empty example memory notes;
• a schema;
• tests;
• documentation for the mechanism.

It should never contain:

• real user preferences;
• real project memory;
• private local paths;
• credentials, cookies, auth files, session logs, or browser profiles;
• product-specific hidden state;
• exported private agent skills or plugin caches.

Quick Start

Create a private capsule:

python3 capsule_memory_kit.py init /tmp/my-agent-memory --build
python3 capsule_memory_kit.py validate /tmp/my-agent-memory

Run the pre-action intake gate:

python3 capsule_memory_kit.py intake "Improve this memory setup and make it current"

Add durable memory to the private capsule:

python3 capsule_memory_kit.py remember /tmp/my-agent-memory \
  --kind project \
  --title "Current task" \
  --text "Ship a runnable memory workflow with validation gates."

Maintain the capsule before ending a session:

python3 capsule_memory_kit.py maintain /tmp/my-agent-memory

Route a task into the smallest relevant memory:

python3 capsule_memory_kit.py route /tmp/my-agent-memory "conflict policy"

Check whether this repository is still public-safe:

python3 capsule_memory_kit.py audit-public .

The tool uses only the Python standard library.

Install As A Command

python3 -m pip install -e .
capsule-memory-kit init /tmp/my-agent-memory --build
capsule-memory-kit intake "Clarify this fuzzy task before editing"
capsule-memory-kit maintain /tmp/my-agent-memory

Commands

Command	Purpose
init ROOT	Create a new private memory capsule.
intake REQUEST	Analyze a fuzzy request before acting: goal hypotheses, missing information, research gate, action gate, and acceptance checks.
build ROOT	Sanitize source notes, build runtime packs, JSONL index, and SQLite FTS index when available.
validate ROOT	Check required files, export safety, content revision consistency, cache-stable generated metadata, and conflict markers.
remember ROOT --kind KIND --title TITLE --text TEXT	Append durable memory to the right source note, then rebuild and validate.
remember ROOT --kind KIND --title TITLE --text-file PATH	Read a longer UTF-8 memory update from a file, then run the same writeback flow.
remember ROOT --kind KIND --title TITLE --text TEXT --conflict	Record an unresolved conflict marker and return with a user-confirmation exit code.
maintain ROOT	Run the session-end maintenance flow: build, conflict check, validate, and cache audit.
route ROOT QUERY	Return the smallest matching memory notes for a task query.
audit-cache ROOT	Report startup surface sizes and volatile metadata risks.
audit-public ROOT	Check that a public template repository does not contain private memory, private paths, vendor-specific terms, or secret-like values.
check-conflicts ROOT	Detect unresolved memory conflict markers that require user preference confirmation.

Capsule Layout

memory-capsule/
  agent-memory-core.json
  AGENTS.md
  adapters/
    generic.md
  memory/
    user.md
    projects.md
    operations.md
  state/
    current/
      runtime/
      index/
      manifests/
  config/
    rules.json

The two startup files are:

1. agent-memory-core.json
2. AGENTS.md

After that, the agent should wait for the task and load only the smallest relevant generated pack or indexed source note.

Intake Gate

The intake gate is the user-facing part of the mechanism. It assumes the user may not yet know the final goal.

For vague or high-risk requests, it returns one of:

• clarify_first
• research_first
• ask_first

For clear low-risk requests, it returns:

• can_execute_with_stated_assumptions

This keeps the agent from acting too early when the real objective, source boundary, output form, or evidence standard is still unclear.

Agent Integration

The full flow is documented in docs/agent-integration.md.

Short version:

1. read agent-memory-core.json;
2. read AGENTS.md;
3. run intake for nontrivial or fuzzy requests;
4. run route after the task is known;
5. load only returned memory notes;
6. write durable updates with remember;
7. run maintain before ending the session.

The manifest shape is described in schema/agent-memory-core.schema.json.

Conflict Rule

Agents may write obvious non-conflicting updates directly. They should stop and ask the user only when a durable preference or source-of-truth claim conflicts with existing memory.

The kit models that rule with explicit markers:

CONFLICT: old preference says X; new preference says Y.

validate and check-conflicts fail while unresolved conflict markers remain.

Cache Policy

Prompt-prefix reuse works best when startup content is stable. The capsule therefore keeps startup context short:

• no timestamps in auto-loaded startup text;
• no current working directory in startup output;
• no generated inventories in startup context;
• no full-capsule scan before the task is known;
• generated manifests use content hashes, not wall-clock timestamps.

audit-cache reports local structural signals that affect cache friendliness. It does not claim to measure any provider's remote cache.

Public Safety

Run this before publishing:

python3 capsule_memory_kit.py audit-public .

The audit rejects private handles, private local paths, vendor-specific names, secret-like strings, raw-session paths, credential files, browser profiles, and generated bytecode/cache noise.

Public Mechanism, Private Memory

Use this public repository as the upstream for mechanism changes: scripts, schemas, templates, tests, and documentation.

Keep real memory in a separate private capsule. When the private capsule develops a better mechanism, port only the generic mechanism back here, then run:

python3 capsule_memory_kit.py audit-public .
make validate

Never port private source notes, generated private indexes, user profiles, local paths, session logs, or exported tool caches into the public repository.

Reproduce

make validate
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
python3 capsule_memory_kit.py audit-public .

Status

This is a public minimal implementation of a local-first memory-capsule pattern. It is a template and CLI scaffold, not a hosted memory service.