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
32 changes: 32 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,38 @@

## Unreleased

## 0.6.0 - 2026-07-11

PAM 0.6.0 adds the optional `amf-memory/v1` Markdown record contract for
source-traceable, scope-aware durable memory.

### Added

- Zero-dependency contract-v1 frontmatter, lifecycle, scope, provenance,
opaque-ID, sealed-claim, RFC 3339 UTC, and canonical-path validation.
- Safe graph-v1 node projections that never expose sealed content or identity
references.
- `memory_record_validate` and `memory_propose_record` MCP tools.
- AMF record creation through the existing proposal/apply review boundary.

### Safety

- Person/relationship scopes and subjects, relationship claims, and
confidential or restricted visibility require an `AES-256-GCM` envelope with external
`keyRef` and canonical AAD hash.
- Proposal and apply enforce ancestor symlink rejection, no-follow reads,
revision/base-hash transitions, per-target locking, archive reservation,
recoverable atomic persistence, supersedes resolution, and real graph collision checks.
- Stale derived-graph warnings survive proposal, archive, and apply responses
with an explicit required graph-reindex follow-up.
- MCP never decrypts records and never creates a canonical record directly.

### Compatibility

- `memoryFormat` and `graphSchemaVersion` remain `graph-v1` and
`pam-graph-v1`.
- Existing logs, graphs, proposals, and MCP tools continue unchanged.

## 0.5.0 - 2026-05-27

PAM 0.5.0 adds a measurable file-only retrieval gate for agents that cannot use
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ The important pieces are:
compact graph-first runtime guide for everyday agent memory lookup.
- [memory/graph/](memory/graph): AI-first JSONL graph memory. Agents can read it
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.
- [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
160 changes: 160 additions & 0 deletions docs/amf-memory-v1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,160 @@
# AMF memory record v1

PAM 0.6.0 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.

## Canonical file

Each record is one Markdown file at:

```text
memory/amf/records/<id>.md
```

`<id>` is the record's opaque `mem_<id>`. The logical record is stored in YAML
frontmatter. PAM accepts a deterministic YAML subset: every top-level field is
one `key: value` line and nested objects/arrays use compact JSON, which is valid
YAML. Sealed records have an empty Markdown body. Plain records may use the body
only for non-claim commentary.

```markdown
---
schema: amf-memory/v1
id: mem_11111111-1111-4111-8111-111111111111
revision: 1
claimType: decision
scope: {"type":"shared","id":"shared:global"}
visibility: shared
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}
provenance: [{"sourceType":"hermes-session","sourceId":"session-stable-id","eventId":"event-idempotency-key","contentSha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","capturedAt":"2026-07-11T10:00:00Z"}]
createdAt: 2026-07-11T10:00:00Z
updatedAt: 2026-07-11T10:00:00Z
---
Optional non-claim commentary.
```

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.

## Sealed claims

A claim must be sealed when any of these is true:

- primary scope is `person` or `relationship`;
- a subject is a `person` or `relationship` identity;
- `claimType` is `relationship`;
- visibility is `confidential` or `restricted`.

The sealed union is stored directly in `claim`:

```json
{
"encoding": "sealed",
"alg": "AES-256-GCM",
"kekId": "kek:<versioned-id>",
"keyRef": "key:<external-record-key-id>",
"iv": "<12 bytes, base64>",
"ciphertext": "<non-empty base64>",
"tag": "<16 bytes, base64>",
"aadSha256": "<sha256>"
}
```

PAM validates the envelope but never decrypts it. The DEK and wrapped key stay
in the external key registry referenced by `keyRef`; they must not enter Git,
logs, proposal metadata, or the PAM graph.

AAD is compact canonical JSON with object keys sorted recursively, encoded as
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:..."}}
```

PAM recomputes its SHA-256 and requires an exact `aadSha256` match. An IV of any
size other than 96 bits, a tag other than 128 bits, empty ciphertext, malformed
`keyRef`, or a mismatched AAD hash fails closed. The sealed record body must be
empty.

## Revision and lifecycle safety

Canonical lifecycle statuses are `active`, `superseded`, `revoked`, and
`expired`. `proposed` exists only in the proposal queue.

For an edit of an existing record, PAM enforces all of the following both when
recording and applying the proposal:

- `revision` is exactly the current revision plus one;
- the proposal's `expectedTargetSha256` equals the SHA-256 of the complete prior
file and `expectedRevision` equals its revision;
- ID, creation time, claim type, scope, and subjects are immutable; plaintext
claims are byte-for-byte immutable;
- visibility can narrow but cannot widen;
- provenance and `lifecycle.supersedes` are append-only;
- only `active` may transition to a terminal lifecycle state;
- `updatedAt` strictly increases.

A claim correction is a new record that names the prior ID in
`lifecycle.supersedes`; it is not an in-place claim rewrite.
PAM resolves every named target inside the current workspace, rejects missing,
symlinked, or invalid targets, and refuses a target newer than the correction.
Provenance entries are ordered by `capturedAt`, and none may be later than the
record's `updatedAt`.

Because revision is authenticated AAD, a sealed record revision necessarily
has a refreshed envelope. PAM requires it to remain sealed, checks the new AAD
hash, and rejects IV reuse. Verifying that the decrypted claim is unchanged is
the authorized Fabric curator's responsibility; PAM never receives the DEK.

## Proposal/apply boundary

Use `memory_propose_record` for creation or `memory_propose_edit` for a metadata
or lifecycle revision. `memory_apply_proposal` is the separate authorized apply
stage. Proposal and apply both reject symlinks in the target or any ancestor,
use no-follow reads, and revalidate schema, revision, hash and graph projection.
Apply is protected by proposal and per-target exclusive locks. Before touching
the target it reserves the final archive path with an atomic no-replace link,
so an archive collision cannot produce an untracked write. The reservation is
`applying`, never `applied`; after the target is atomically persisted and
fsynced it is finalized to `applied`. A retry recovers either state
idempotently and verifies the persisted content hash before reporting success.
An `applying` reservation is bound to the complete immutable proposal artifact,
including source, diff/provenance, rationale, findings, validation and any
future proposal fields—not only its id, target and content hash. A mismatch
cannot overwrite the reservation, persist the target, or remove the live
proposal.
If the live proposal still exists, recovery also requires the archive proposal
identity, target, proposed/persisted hashes, and validation-warning summary to
match before the proposal artifact can be removed.

Each lock carries a PID, host, random nonce, acquisition time, and heartbeat.
Takeover is fail-closed: it is allowed only when the heartbeat is stale and the
same-host owner PID is provably dead. Foreign-host, malformed, fresh, or live
locks require operator review or a later retry. Heartbeat and release verify
both the owner token and inode, so an old owner cannot update or remove a lock
that has been replaced.

The graph node returned by validation is derived. It is checked both standalone
and against the workspace's actual graph-v1 files. A collision with a
non-memory node fails. An older `memory-record` projection is allowed only as a
bounded stale derivative and produces a warning requiring regeneration after
apply. Sealed and non-shared claims project only a generic digest and never
identity IDs, ciphertext, scope IDs, or key references.

That warning is durable across the whole review boundary. Proposal results and
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.

## Validation

```bash
npm test
npm run migrations:check
npm run mcp:smoke
```
49 changes: 39 additions & 10 deletions docs/mcp-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,19 @@ 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
15 tools under the `pam` namespace:
17 tools under the `pam` namespace:

- `pam_version`, `memory_state`, `maintenance_config`: context tools
- `memory_list`, `memory_read`, `memory_search`: safe filesystem reads under `memory/`
- `memory_record_validate`: validates `amf-memory/v1` Markdown and returns a safe graph projection
- `graph_query`, `graph_stats`, `graph_validate`, `graph_reindex`: graph tools
- `memory_audit`: hygiene checks, returns findings
- `memory_propose_edit`: records a proposal artifact under `memory/maintenance/proposals/`; never mutates the target file
- `memory_propose_record`: validates an AMF record and records a create proposal; never writes the record directly
- `memory_append`: appends a dated section to a managed log; refuses unmanaged paths
- `memory_apply_proposal`: applies a previously-recorded proposal after re-validating against current content; archives the artifact
- `memory_apply_proposal`: applies a recorded proposal through an exclusive
`applying` reservation, atomic target persistence, `applied` finalization,
and idempotent recovery
- `maintenance_run`: wraps the maintenance CLI (defaults to dry-run)

Write paths through the server are bounded:
Expand All @@ -25,7 +29,10 @@ Write paths through the server are bounded:
- `memory_apply_proposal` only writes to whatever target a previously-recorded
proposal already passed through the safety validator at propose time, and
re-validates everything (protected paths, drift, graph integrity) before
applying.
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.
- `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 @@ -135,7 +142,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 15 listed above.
always one of the 17 listed above.

## Workspace selection

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

## Safety surface

`memory_propose_edit` is the only tool that produces an artifact intended for
review. It rejects, with a clear error message:
`memory_propose_edit` and `memory_propose_record` are the only tools that
produce artifacts intended for review. 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 @@ -172,11 +179,16 @@ review. It rejects, with a clear error message:
- diffs over 64 KB;
- unified-diff hunks whose `before` doesn't match current content;
- JSONL edits whose result fails `validateGraph`.
- AMF records that fail schema, lifecycle, scope, provenance, sealing, or path
validation.

Proposal artifacts are JSON files under `memory/maintenance/proposals/`.
Applying a proposal is a manual step that the human takes after review,
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).

## Write tools

### `memory_append`
Expand Down Expand Up @@ -210,18 +222,35 @@ Inputs:
- `proposalId` (required): the id of a JSON artifact under
`memory/maintenance/proposals/<id>.json`.

The server:
The server uses this state machine:

1. Loads the proposal.
1. Acquires the exclusive proposal lock and loads the archive/proposal state.
A pending or `applying` operation also acquires the per-target lock before
target validation or persistence.
2. Re-runs the same safety checks `memory_propose_edit` ran at propose time
(protected paths, workspace escape, symlinks).
3. Re-applies the diff against the *current* target content. If the file has
drifted since the proposal was recorded (`before` no longer matches, or
unified-diff hunks don't align), apply is rejected and the artifact is
untouched.
4. For JSONL targets, runs `validateGraph` on the proposed result.
5. On success, writes the new content, renames the artifact to
`<id>.applied.json` with `appliedAt` and `status: "applied"` added.
5. Exclusively reserves `<id>.applied.json` with `status: "applying"` before
touching the target. The reservation binds the complete immutable proposal
identity. A pre-existing foreign, malformed, or mismatched archive is a
collision and fails closed without overwriting the archive, writing the
target, or deleting the live proposal.
6. Atomically persists and fsyncs the target, then reloads and verifies that
the same reservation still owns the archive path.
7. Finalizes the archive as `status: "applied"` with `appliedAt` and the
persisted content hash.
8. Removes the live `<id>.json` proposal only after finalization succeeds.

Retries are idempotent. A matching `applying` reservation resumes the operation
whether or not the target was already persisted. A matching `applied` archive
is recovered only after its proposal identity and target hash are verified; a
lingering live proposal is removed only after that verification. If persistence
succeeds but finalization does not, the live proposal and recoverable archive
state remain for a later retry.

Drift detection is intentional. A proposal that fails apply is a signal that
the target changed since review; re-run the curator, get a fresh proposal,
Expand Down
9 changes: 6 additions & 3 deletions memory/agent-memory/pam-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,9 +76,12 @@ context."

## Updating Memory

For durable AI memory, add or update graph records first, then keep markdown
logs/indexes compatible. Do not store secrets, credentials, private data, raw
private conversations, or machine-specific paths.
For classic PAM memory, add or update graph records first, then keep markdown
logs/indexes compatible. When `pam.version.json` enables `amfMemoryV1`, the
canonical `memory/amf/records/` Markdown record comes first and its graph node is a
safe derived projection. Create it through the proposal/apply flow and validate
it again before graph maintenance. Do not store secrets, credentials, private
data, raw private conversations, or machine-specific paths in plaintext.

In OpenClaw workspaces, first map PAM concepts to existing OpenClaw-native or
workspace-owned memory. Write only PAM-owned files by default, and do not edit
Expand Down
13 changes: 13 additions & 0 deletions memory/agent-memory/pam.md
Original file line number Diff line number Diff line change
Expand Up @@ -603,6 +603,19 @@ YYYY-MM-DD.
Links or references to related notes, decisions, runbooks, or raw sources.
```

### 8.4 Structured scoped memory records

An implementation that needs machine-validated scopes, lifecycle, provenance,
or sealed private claims may enable the optional `amf-memory/v1` record
contract. These records remain Markdown-first and use the normal PAM
proposal/apply review boundary.

The record file is canonical. Graph, full-text, vector, and external memory
engine entries are derived and replaceable. Person, relationship,
confidential, and restricted claims MUST be sealed; PAM validates their
envelope but does not own keys or decrypt content. See
`docs/amf-memory-v1.md` for the complete portable contract.

---

## 9. llm-wiki role
Expand Down
9 changes: 6 additions & 3 deletions memory/pam.version.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"pamVersion": "0.5.3",
"pamVersion": "0.6.0",
"memoryFormat": "graph-v1",
"graphSchemaVersion": "pam-graph-v1",
"features": {
Expand All @@ -16,7 +16,10 @@
"fileOnlyCoverage": true,
"llmRetrievalBenchmark": true,
"benchmarkThresholdGate": true,
"tightBenchmarkRegressionGate": true
"tightBenchmarkRegressionGate": true,
"amfMemoryV1": true,
"sealedMemoryRecords": true,
"memoryRecordMcpTools": true
},
"updated": "2026-06-02"
"updated": "2026-07-11"
}
Loading