Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,56 @@

## Unreleased

### Added

- PAM 0.6.2 decision receipts and a separately authorized deterministic
applicator with durable apply-receipt outbox and crash recovery.

- Mandatory exact `amf-memory/v1` confidence metadata with finite score,
evidence basis, UTC assessment time, AAD binding, and revision-safe changes.

- Deterministic AMF candidate queue, versioned reviews, deduplication, policy
decisions, and `approved_pending_apply` receipts.
- Strict, HMAC-chained append-only curator decision ledger with an authenticated
sequence/length/head anchor and redacted fail-closed status output.
- `memory_curator_submit`, `memory_curator_review`,
`memory_curator_status`, and `memory_curator_git_plan` MCP tools plus the
`memory:curator` CLI.
- Fail-closed Git writer plan abstraction, disabled and dry-run-only by default;
it refuses protected branches and direct push.

### Safety

- Applicator proposal digests are now enforced inside `applyProposal` after the
per-target lock and before archive reservation or target persistence, closing
the post-`prepared` proposal-swap TOCTOU window.

- The curator accepts complete `amf-memory/v1` records only, never RAW
transcripts or arbitrary source payloads, and has no direct canonical write
path.
- Automatic approval is disabled by default. Explicitly enabled eligible
candidates still require the separate `memory:apply-receipt` applicator.
- Candidate/review artifacts require an external ledger key; manual review and
apply require a separately allowlisted server-side capability. Recovery
verifies the exact applied archive and canonical target before success.
- The head anchor lives outside the curator queue tree and is never recreated
for a non-empty ledger. Dedup/status fail on any unverified artifact and
reconcile promotion events with applied-archive history. Ledger record,
source, and target references are HMAC-only.
- The anchor and initialized marker now live in a pre-provisioned external
`0700` state root outside the workspace, paired with a workspace sentinel.
Deterministic crash recovery covers candidate-fsync and ledger-before-anchor
boundaries; strict-prefix anchor advancement requires an allowlisted admin
capability through CLI/MCP.
- Review-fsync and apply-before-ledger boundaries now recover only from one
exact MAC-authenticated candidate-version decision or applied archive. Exact
retries converge; explicit admin recovery remains capability-gated and
refuses forged, unrelated, or ambiguous external-ahead state.
- Automatic-policy retries additionally bind the normalized policy snapshot,
deterministic actor/action/idempotency, and exact original submission. Both
queued-review and auto-promote crash boundaries converge without weakening
the manual-review contract.

## 0.6.0 - 2026-07-11

PAM 0.6.0 adds the optional `amf-memory/v1` Markdown record contract for
Expand Down
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,11 @@ The important pieces are:
directly without Node, npm, a database, or embeddings.
- [docs/amf-memory-v1.md](docs/amf-memory-v1.md): optional source-traceable,
scope-aware Markdown record contract with sealed private bodies and safe
graph projections.
graph projections; PAM 0.6.1 requires structured confidence and binds it
into sealed-record AAD.
- [docs/amf-curator.md](docs/amf-curator.md): deterministic candidate queue,
versioned decision receipts, separately authorized receipt application, and fail-closed
dry-run Git writer plan.
- [memory/agent-memory/pam.md](memory/agent-memory/pam.md): the Portable Agent
Memory constitution. This is the setup/protocol reference agents should
follow when changing or auditing PAM itself.
Expand Down
158 changes: 158 additions & 0 deletions docs/amf-curator.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
# AMF curator and receipt applicator

PAM 0.6.2 separates memory judgment from canonical mutation. Both components
accept complete `amf-memory/v1` records only; neither accepts RAW transcripts,
message bodies, decryption keys, or arbitrary source payloads.

## Authority boundary

The curator has only `memory:curate`. It validates, deduplicates, records a
versioned review, and emits an authenticated decision receipt with exactly one
outcome:

- `review_required`;
- `rejected`;
- `approved_pending_apply`.

The curator never calls PAM proposal/apply, never reports `promoted`, and never
writes `memory/amf/records/`. `autoPromote` is retained as the compatibility
name for policy-based automatic approval, but it only emits
`approved_pending_apply`. Confidence selects a policy route; it grants no
capability and cannot expand scope or visibility.

The applicator has a distinct `memory:apply-receipt` credential. It accepts only
the latest authenticated `approved_pending_apply` receipt, verifies its
candidate, revision, decision digest, policy digest, and lifecycle-at-decision,
then uses the existing `memory_propose_record`/`memory_propose_edit` and
`memory_apply_proposal` implementation. Auto-approval cannot bypass it.

## Durable artifacts

Curator artifacts are HMAC-authenticated and mode `0600`:

```text
memory/amf/curator/
├── queue/<candidate-id>.json
├── reviews/<decision-id>.json
├── decision-receipts/<decision-id>.json
└── decisions.jsonl
memory/amf/curator.initialized.json
```

The append-only decision ledger is typed, sequence-numbered, HMAC-chained, and
anchored in a pre-provisioned external `0700` state directory. IDs are derived
from stable idempotency keys. An exact retry returns the existing artifact;
altered content, decision, policy, or authenticated artifact fails closed.

Applicator state and its transport outbox are independently authenticated:

```text
memory/amf/applicator/
├── state/<apply-id>.json
└── outbox/<apply-id>.json
```

The recoverable state machine is:

```text
prepared -> pam_applied -> receipt_queued -> fabric_acked
```

The apply receipt is discriminated as `memory_apply_receipt` and binds
`proposalId`, `decisionId`, `decisionDigest`, `policyDigestAtApply`,
`canonicalRecordId`, `revision`, `canonicalLifecycleAtDecision`, and SHA-256
digests of the proposal, applied archive, and canonical target. PAM verifies the
archive and target before queuing the receipt.

The `prepared` state stores the canonical proposal digest. `applyProposal`
re-reads the proposal after acquiring both its proposal lock and the canonical
target lock, then compares that digest before reservation or persistence. A
valid proposal altered after `prepared`, or swapped while the target lock is
being acquired, fails closed without changing the target or archive.

Crashes after every state boundary converge under the exact idempotency key.
A crash after PAM apply is recovered through PAM's applied archive; a crash
after Fabric ACK relies on the sink treating `applyId` as its idempotency key.
Outbox or state alteration fails authentication.

## Transport

The default transport is disabled, leaving a durable `receipt_queued` outbox.
Tests may inject a synchronous idempotent sink. HTTP configuration requires an
HTTPS endpoint from the configured environment variable, but this release does
not perform live HTTP: dispatch fails closed and leaves the receipt queued until
an audited Fabric transport is integrated.

## Configuration

```json
{
"amfCurator": {
"version": "amf-curator-policy/v1",
"autoPromote": false,
"ledgerKeyEnv": "PAM_CURATOR_LEDGER_KEY",
"stateDirEnv": "PAM_CURATOR_STATE_DIR",
"reviewerTokenEnv": "PAM_CURATOR_REVIEWER_TOKEN",
"reviewers": [{
"tokenSha256": "<sha256>",
"actorId": "service:memory-curator",
"capabilities": ["memory:curate"]
}],
"gitWriter": { "enabled": false, "dryRunOnly": true }
},
"amfApplicator": {
"version": "amf-receipt-applicator/v1",
"tokenEnv": "PAM_APPLICATOR_TOKEN",
"applicators": [{
"tokenSha256": "<sha256>",
"actorId": "service:memory-applicator",
"capabilities": ["memory:apply-receipt"]
}],
"transport": {
"kind": "disabled",
"endpointEnv": "PAM_FABRIC_RECEIPT_ENDPOINT"
}
}
}
```

The Git writer remains disabled and dry-run-only. It cannot push, write a
protected branch, merge, or deploy.

## CLI and MCP

```bash
npm run memory:curator -- submit --input candidate.json
npm run memory:curator -- review --input review.json
npm run memory:curator -- apply --input application.json
npm run memory:curator -- status
npm run memory:curator -- recover --input recovery.json
npm run memory:curator -- git-plan --input git-plan.json
```

MCP adds `memory_receipt_apply` alongside `memory_curator_submit`,
`memory_curator_review`, `memory_curator_status`, `memory_curator_recover`, and
`memory_curator_git_plan`. Curator recovery supports only `advance-anchor` and
`recover-review`; apply recovery is the applicator's exact retry path.

## Recovery checks

1. Stop on an invalid candidate/review/receipt MAC, ledger chain, anchor, state,
or outbox.
2. Retry candidate or review writes with the exact original input.
3. Use `advance-anchor` only for a verified strict-prefix anchor.
4. Retry application with the exact `decisionId` and idempotency key. PAM's
proposal/archive checks determine whether to apply or recover.
5. Never delete ledgers, sentinels, state, or outbox files to clear an error.
6. Treat commit, push, PR, deploy, restart, and live transport as separate
approval gates.

Validation:

```bash
node --test tools/test-memory-curator.mjs
npm test
npm run migrations:check
npm run mcp:smoke
git diff --check
```
20 changes: 18 additions & 2 deletions docs/amf-memory-v1.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# AMF memory record v1

PAM 0.6.0 implements the public `amf-memory/v1` file-first contract used by
PAM 0.6.1 implements the public `amf-memory/v1` file-first contract used by
Agent Memory Fabric. It is additive: existing PAM logs and graph-v1 workspaces
continue to work unchanged.

Expand All @@ -26,6 +26,7 @@ revision: 1
claimType: decision
scope: {"type":"shared","id":"shared:global"}
visibility: shared
confidence: {"score":0.99,"basis":"reviewed","assessedAt":"2026-07-11T10:00:00Z"}
subjects: [{"identityId":"agent:22222222-2222-4222-8222-222222222222","role":"owner"}]
claim: {"encoding":"plain","text":"A portable source-backed decision."}
lifecycle: {"status":"active","validFrom":"2026-07-11T10:00:00Z","validTo":null,"supersedes":[],"revokedAt":null,"revocationReason":null}
Expand All @@ -40,6 +41,13 @@ Unknown fields and unknown major schemas fail validation. Timestamps are strict
RFC 3339 UTC (`Z`), not local offsets. Provenance is non-empty and contains
pointers and hashes, never embedded RAW.

`confidence` is mandatory and contains exactly `score`, `basis`, and
`assessedAt`. `score` is a finite number from `0` through `1`; `basis` is one
of `observed`, `asserted`, `inferred`, or `reviewed`; `assessedAt` is RFC 3339
UTC and falls between `createdAt` and `updatedAt`. Unknown or missing fields
fail closed. A revision may reassess confidence, but any change requires a
strictly newer `assessedAt`, which may never move backwards.

## Sealed claims

A claim must be sealed when any of these is true:
Expand Down Expand Up @@ -73,7 +81,7 @@ UTF-8. In addition to record routing fields, it binds the envelope algorithm
and external key identifiers:

```json
{"schema":"...","id":"...","revision":1,"claimType":"...","scope":{},"visibility":"...","subjects":[],"envelope":{"alg":"AES-256-GCM","kekId":"kek:...","keyRef":"key:..."}}
{"schema":"...","id":"...","revision":1,"claimType":"...","scope":{},"visibility":"...","confidence":{"score":0.99,"basis":"reviewed","assessedAt":"2026-07-11T10:00:00Z"},"subjects":[],"envelope":{"alg":"AES-256-GCM","kekId":"kek:...","keyRef":"key:..."}}
```

PAM recomputes its SHA-256 and requires an exact `aadSha256` match. An IV of any
Expand All @@ -95,6 +103,7 @@ recording and applying the proposal:
- ID, creation time, claim type, scope, and subjects are immutable; plaintext
claims are byte-for-byte immutable;
- visibility can narrow but cannot widen;
- confidence reassessment requires a strictly newer assessment timestamp;
- provenance and `lifecycle.supersedes` are append-only;
- only `active` may transition to a terminal lifecycle state;
- `updatedAt` strictly increases.
Expand Down Expand Up @@ -151,6 +160,13 @@ artifacts, applied archives, and apply results expose `graphProjectionStale`,
`regenerateAfterApply`, and a required `npm run memory:graph:index` follow-up.
An apply coordinator must not discard that follow-up when marking its task done.

## Optional curator

The deterministic AMF curator adds an idempotent queue, policy/review decisions,
deduplication, and proposal/apply orchestration without changing this record
contract. It is disabled for automatic promotion by default and never accepts
RAW transcripts. See [AMF deterministic curator](amf-curator.md).

## Validation

```bash
Expand Down
33 changes: 27 additions & 6 deletions docs/mcp-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ markdown + JSONL contract is unchanged; the server is purely additive runtime.
## What you get

The server runs locally over stdio (no network, no daemon, no port) and exposes
17 tools under the `pam` namespace:
22 tools under the `pam` namespace:

- `pam_version`, `memory_state`, `maintenance_config`: context tools
- `memory_list`, `memory_read`, `memory_search`: safe filesystem reads under `memory/`
Expand All @@ -20,6 +20,18 @@ The server runs locally over stdio (no network, no daemon, no port) and exposes
- `memory_apply_proposal`: applies a recorded proposal through an exclusive
`applying` reservation, atomic target persistence, `applied` finalization,
and idempotent recovery
- `memory_curator_submit`, `memory_curator_review`, and
`memory_curator_status`: deterministic AMF candidate/review orchestration
with authenticated artifacts, a redacted HMAC-chained decision ledger, and a
sequence/length/head anchor
- `memory_receipt_apply`: separately authorized receipt applicator; verifies an
`approved_pending_apply` decision, uses PAM proposal/apply, and queues a
digest-bound `memory_apply_receipt`
- `memory_curator_git_plan`: fail-closed Git writer planning; disabled and
dry-run-only by default, with no Git execution or push path
- `memory_curator_recover`: curator-only recovery for an existing strict-prefix
external anchor or one exact review artifact; apply recovery is an exact
`memory_receipt_apply` retry
- `maintenance_run`: wraps the maintenance CLI (defaults to dry-run)

Write paths through the server are bounded:
Expand All @@ -31,8 +43,13 @@ Write paths through the server are bounded:
re-validates everything (protected paths, drift, graph integrity) before
applying. Archive collisions and proposal-identity mismatches fail closed
before target persistence.
- `memory_propose_record` is the only MCP path for creating an AMF record;
creation remains pending until `memory_apply_proposal` re-validates it.
- `memory_propose_record` is the only underlying proposal path for creating an
AMF record. Only the receipt applicator delegates to it.
- The curator emits `review_required`, `rejected`, or
`approved_pending_apply`; it never applies or reports promotion.
- Curator decisions require `memory:curate`; canonical application requires a
distinct server-side `memory:apply-receipt` capability. Client-supplied
reviewer labels never authorize a change.
- `graph_reindex` writes only the derived `memory/graph/catalog.json`.
- `maintenance_run` is gated by `config` and defaults to dry-run.

Expand Down Expand Up @@ -142,7 +159,7 @@ set to the repo root. The exact config file location depends on your client.
Each host prefixes MCP tools with the server name. Claude Code surfaces them as
`mcp__pam__memory_audit`, `mcp__pam__graph_validate`, and so on. Cursor and
Codex use similar prefixes. The unprefixed tool name within the server is
always one of the 17 listed above.
always one of the 22 listed above.

## Workspace selection

Expand All @@ -169,8 +186,10 @@ one-file change in `tools/lib/mcp-transport.mjs`.

## Safety surface

`memory_propose_edit` and `memory_propose_record` are the only tools that
produce artifacts intended for review. They reject, with a clear error message:
`memory_propose_edit`, `memory_propose_record`, and the curator tools produce
artifacts intended for review. The separate receipt applicator delegates
canonical changes to the proposal/apply tools. They reject, with a clear error
message:

- paths matching `config.protectedPaths` (`AGENTS.md`, `CLAUDE.md`, `memory/agent-memory/`, `memory/sources/`);
- paths that resolve outside the workspace;
Expand All @@ -188,6 +207,8 @@ typically via `memory_apply_proposal` below.

For the record schema, sealed-claim rules, lifecycle constraints, and safe graph
projection, see [AMF memory record v1](amf-memory-v1.md).
For curator policy, idempotency, recovery, and the redacted decision ledger,
see [AMF deterministic curator](amf-curator.md).

## Write tools

Expand Down
15 changes: 12 additions & 3 deletions memory/pam.version.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"pamVersion": "0.6.0",
"pamVersion": "0.6.2",
"memoryFormat": "graph-v1",
"graphSchemaVersion": "pam-graph-v1",
"features": {
Expand All @@ -19,7 +19,16 @@
"tightBenchmarkRegressionGate": true,
"amfMemoryV1": true,
"sealedMemoryRecords": true,
"memoryRecordMcpTools": true
"memoryRecordMcpTools": true,
"memoryRecordConfidence": true,
"deterministicMemoryCurator": true,
"curatorDecisionLedger": true,
"curatorGitWriterDryRun": true,
"curatorExternalStateAnchor": true,
"curatorForwardRecovery": true,
"curatorDecisionReceipts": true,
"separateReceiptApplicator": true,
"durableApplyReceiptOutbox": true
},
"updated": "2026-07-11"
"updated": "2026-07-12"
}
Loading