Memory Lab

A small AWS-native memory lab where cognitive memory can mutate and lineage is immutable, append-only, and replayable.

Behavior is a moving target. History is not.

Start here

If you are an agent or a human new to this repo, read specs/AGENT_PRIMER.md. That is enough to start.

After the primer, the only other required reading is AGENTS.md. Deeper specs and notes are on the primer's deep-dive list and should be opened only when the task asks for them.

Repo layout

• stacks/ — AWS CDK infra (S3 Tables, S3 Vectors, ingress bucket, Athena, EventBridge, SQS). See stacks/README.md.
• src/ — engine (lineage_engine, storage), explicit memory, implicit memory, ingestion, experiments, epistemic_triangle (v7 record/assertion taxonomy), heliotime + timekeeping (TAI capture and physical_moment construction).
• specs/ — load-bearing contracts. Start with AGENT_PRIMER.md.
• notes/ — theory and design pivots. Not contracts.

Non-negotiable invariants

1. Memory behavior can change; lineage history must not be rewritten.
2. S3 Tables is canonical lineage. The active table is named by AWS_ATHENA_TARGET_TABLE_FQN in .env (and the current schema_version lives in src/types.py::EVENT_SCHEMA_VERSION). Earlier-epoch tables are historical containers; no new writes. Do not hardcode the version in docs — see AGENTS.md § Documentation conventions.
3. S3 Vectors is a rebuildable recall index, not source of truth.
4. Do not auto-resolve contradictions.
5. No implicit decision is silent: every trigger evaluation emits an event.

Quick start

Requirements: uv, AWS profile stack-research, AWS_REGION set, .env populated (see .env.example).

Synth and deploy infra:

make synth
make deploy

Run the implicit regression suite:

make implicit-regression

Run a single explicit experiment (e1..e12):

make exp-e1

Run a single implicit loop tick (no Makefile target):

PYTHONPATH=. uv run --project stacks python -m src.implicit_memory.run_loop

Run any experiment by name (e1..e12, im-a..im-u, im-aws, im-regression):

PYTHONPATH=. uv run --project stacks python -m src.run_experiment <name>

Athena ingestion (raw to canonical):

make ingest

See the Makefile for the full list of targets.

Timekeeping kernel (src/heliotime, src/timekeeping)

Lineage time in this lab has two coordinates. The mechanism is TAI — uninterrupted SI seconds, counted continuously, no leap-second discontinuities. The position is heliocentric ecliptic: solar age in megayears and Earth's heliocentric ecliptic longitude in degrees at the moment of capture. Every canonical event carries both in its physical_moment block. Replay regenerates the same bytes; the coordinate stays legible on any timescale a future replay will inhabit.

src/heliotime is the kernel. Pure functions take an explicit input moment (datetime, ISO string, or astropy.time.Time) and produce a PhysicalMoment (tai_iso, solar_age_myr, ecliptic_lon_deg). One function reads the wall clock — heliotime.now() — and it is named so replay paths cannot reach it by accident. astropy is the only dependency.

src/timekeeping layers the rest of the v7 envelope on top:

• context.py — TimeContext and a deterministic time_context_id (SHA-256 of a canonical-JSON serialization of the content fields; idempotent re-declaration).
• hlc.py — Kulkarni-2014 hybrid logical clock keyed off physical_moment.tai_iso. Replay-deterministic by construction.
• batch.py — canonical_batch_committed markers that resolve "same atomic batch" without relying on wall-clock proximity.
• events.py — payload builders for time_context_declared, canonical_table_genesis, and canonical_table_boundary.

Standalone package potential

The kernel is self-contained by design. heliotime depends only on astropy; timekeeping depends on heliotime and the Python standard library. Neither imports from src/lineage_engine, src/storage, or any AWS surface. Any append-only system that needs replay-stable physical time and a coordinate that survives civil-calendar drift can adopt the same shape — event-sourced stores, distributed ledgers, simulation harnesses, log pipelines.

A standalone Python package (working name: heliotime) is a natural next step, and the migration is cheap by construction: lift src/heliotime/ and src/timekeeping/, publish to PyPI, add the dependency to pyproject.toml, delete the in-tree copy. The spec is specs/TAI_TIMEKEEPING.md; the seed is notes/solar_time/.

Where to read next

• specs/AGENT_PRIMER.md — what this system is, in one file.
• AGENTS.md — rules for coding agents.

Anything else is on the primer's deep-dive list.