in reviewhumanPR #358Memory

gitmem: Track seller with git-backed memory, plus hand-edited-memory and crash-restart tests

gitmem is a memory layer for AI agents that stores each remembered fact as a file in a git repository, so every change to an agent's memory has a history: what changed, when, who made the change and why.

Author

Status
In review
Opened on
Nov 11
Branch
integration/gitmem-track-seller

Description

The pitch.

## Summary

**gitmem** is a memory layer for AI agents that stores each remembered fact as a file in a git repository, so every change to an agent's memory has a history: what changed, when, who made the change and why. It can also check what an agent remembers against what actually happened.

This PR adds `examples/gitmem/`: a Track seller whose memory is a gitmem store, plus a check that compares the seller's memory against Town's own record of the run. It covers six cases, including memory edited by hand between restarts and a crash before ack. No Town code is changed.

## Integration

- **`gitmem_seller.py`**: a mailbox seller that uses `TownClient` (join, claim with lease and fence, send, ack). Its memory is a gitmem store at `$STATE_DIR/memory`. For each quote it remembers the reply, the total and whether it was reported, and it uses that memory to answer resends after a restart. The ack note includes a `gitmem` object with the memory commit.
- **`gitmem_observe.py`**: runs after the Track run. It rebuilds what Town recorded (from `events.jsonl`: reply id and fingerprint, the total from the buyer's ack, refused resends) into a separate "observed" lane of the same store. It then reconciles that lane against what the seller remembered and writes `gitmem-check.json` into the evidence bundle.
- **`run_check.py`** runs the six cases; **`test_gitmem_check.py`** wraps them for pytest. It is not in Town's default `testpaths` and skips if gitmem is not available.
- **`evidence/<case>/`** holds the recorded run for each case: the canonical records, attestation, `report.md`, `gitmem-check.json`, the memory's full `git log -p` and the seller's log.
- **Separate repository:** the gitmem library lives in [amangang3/nandatown-memory-mvp](https://github.com/amangang3/nandatown-memory-mvp). Its store is adapted from another author's project, so it is not copied into Town. The adapter imports it from a pinned checkout named by `GITMEM_SRC`. No hosted service and no model account are needed.

## Reproduce

- **Nanda Town commit:** `6f9a7c064486c4a0ae9242f1ff341b8a4aad0244` (main at time of PR; package version 0.2.0, Track evaluator 0.5.0)
- **Project version:** `amangang3/nandatown-memory-mvp@121a10dc214a6f7475ff764a33f23d2be6d63d9d`
- Python 3.11+, git

```bash
# Town, from this branch
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e '.[dev]'

# gitmem, at the pinned commit
git clone https://github.com/amangang3/nandatown-memory-mvp /tmp/gitmem
git -C /tmp/gitmem checkout 121a10dc214a6f7475ff764a33f23d2be6d63d9d
export GITMEM_SRC=/tmp/gitmem/memory_mvp

# the compatibility check: six Track runs, about 20 seconds
python examples/gitmem/run_check.py
# or as pytest
python -m pytest -q examples/gitmem
# a single case
python examples/gitmem/run_check.py --only edit-total-trust
```

## Results and limitations

| Case | Boundary tested | Expected | Observed |
|---|---|---|---|
| intact | normal run | PASSED, memory matches Town | PASSED, 0 contradictions |
| edit-total-verify | remembered total hand-edited between restarts; seller checks git before reading | edit undone, PASSED | PASSED, 2 edits restored |
| edit-total-trust | same edit; seller trusts the file | failure detected | **INCOMPLETE**: coordinator rejected the resend (`identity_reuse_rejected`); observer found 2 contradictions |
| delete-trust | remembered reply deleted; seller trusts memory | double application visible | PASSED by Town, but memory history shows the quote applied twice |
| delete-verify | same deletion; seller restores from git | PASSED, applied once | PASSED, applied once |
| crash-restart | seller answers, then exits 3 before ack; runner restarts it | PASSED, no duplicate | PASSED |

All six cases matched expectations in 4 full repeated runs. Town's own test suite still passes (1865 passed).

Findings:
- **Shutdown can interrupt a memory write.** The runner stops participants with `killpg(SIGTERM)` and then SIGKILL 0.5 s later. This also k

…

Try it

Open PR on GitHubView diff

Checkout locally

git fetch origin pull/358/head:pr-358
git checkout pr-358