with-agent-memory

Minimal runnable reference stack for @event4u/agent-memory. Four commands from clone to a green end-to-end smoke test.

What this is: the shortest honest answer to "does agent-memory actually work end-to-end for my project?" — without having to read the full docs first.

What this is not: a tutorial, a production template, or the agent-memory source tree. For transport-specific snippets (Claude Desktop, Cursor, GitHub Actions, …) go to agent-memory · docs/integrations.md.

4-step quickstart

# 1. Clone this repo
git clone https://github.com/event4u-app/with-agent-memory
cd with-agent-memory

# 2. Boot postgres + the agent-memory sidecar
docker compose up -d

# 3. Run the end-to-end smoke
./smoke.sh

# 4. (Optional) Interact directly
docker compose exec agent-memory memory --help
docker compose exec agent-memory memory retrieve "invoice calculation"

Expected tail of smoke.sh:

✅  memory health: status=ok  contract_version=1
✅  propose: proposal_id=…
✅  promote: status=validated
✅  retrieve: contract=v1 status=ok indexed=1 filtered=1 (trust floor, by design)

✨  with-agent-memory smoke passed — propose → promote → retrieve is green

filtered=1 is not a failure — see Trust lifecycle below.

What boots

Service	Image	Role
postgres	pgvector/pgvector:pg17	Storage for memory entries, events, embeddings
agent-memory	ghcr.io/event4u-app/agent-memory:main	CLI + MCP server; applies migrations on first boot

.agent-memory.yml in this repo is an example of the C1 project-local config layer — edit repository, trust.threshold, or retrieval.token_budget to see the chain in action. The file is optional; agent-memory runs without it.

What the smoke tests

Step	Proves
memory health returns status=ok and contract_version=1	Sidecar is up, retrieval contract matches
memory propose --impact low --gate-clean	Quarantine path works, extraction guard is green
memory promote <id> --skip-duplicate-check	Promotion pipeline passes all non-duplicate gates
memory retrieve <title> pipes through and indexes the entry (totalCandidates≥1)	BM25 + vector + RRF wiring is green; trust filter governs visibility

Trust lifecycle

A freshly promoted entry sits at trust score 0.2 (baseline floor for entries without evidence refs). Both retrieval thresholds — the default (0.6) and the low-trust mode (0.3) — are above that floor, so retrieve will find the entry in the index but filter it out of the served result set. This is the designed behavior:

Event	Trust effect
propose	trust_score ← confidence (e.g. 0.7), status quarantine — not served
promote	trust_score ← calculateTrustScore(...) → 0.2 for 0-evidence entries, status validated
Retrieval hit	+0.1 per batch of access-count growth (cap +0.1)
Evidence verification	Per-evidence contribution (scales 0.4 → 0.6 → 0.7+)
TTL half-life passed	−0.3 linear decay, stales on expiry

The smoke therefore asserts the pipeline shape, not hit-count:

• contract_version=1 → retrieval contract intact
• status=ok → no upstream error
• totalCandidates≥1 → the promoted entry did reach BM25+vector
• filtered=1 → trust filter behaved as specified

To see a real hit, promote with evidence refs (via memory ingest --file/--symbol followed by a validator pass) or invoke retrieve repeatedly on the same title until access-count pushes score above 0.3.

Troubleshooting

docker compose up fails to pull the image. By default this stack tracks ghcr.io/event4u-app/agent-memory:main — the head of agent-memory's main branch, rebuilt on every push. To pin a stable release once one is published, set IMAGE_TAG to the desired tag:

IMAGE_TAG=v1.1.0 docker compose up -d --pull always

If the pull itself fails, force a fresh fetch:

docker compose pull && docker compose up -d

agent-memory did not reach 'healthy' within 120s. First-time boot pulls Postgres + pgvector + the sidecar image and runs migrations. On slow networks the default window is tight. Retry once with a warm cache, or inspect:

docker compose logs agent-memory

promote returned status=quarantine_still. The entry failed a gate. The most common causes: missing scenarios (--impact normal or higher requires three --scenario flags — smoke.sh sidesteps this with --impact low), or the extraction guard flagging unrelated diff noise. Read the JSON returned by promote — the gates field names the failing rule.

Drift canary

The weekly GitHub Action .github/workflows/weekly-drift.yml runs this same smoke against ghcr.io/event4u-app/agent-memory:main. A red run means agent-memory/main regressed against the published copy-paste flow in this repo — long before any user feels it.

Links

• agent-memory repository — https://github.com/event4u-app/agent-memory
• Full CLI reference — https://github.com/event4u-app/agent-memory/blob/main/docs/cli-reference.md
• Integration snippets index — https://github.com/event4u-app/agent-memory/blob/main/docs/integrations.md
• Contract stability policy — https://github.com/event4u-app/agent-memory/blob/main/docs/contract-stability.md