AMCS-0.1

Agent Memory Canonicalization Standard (AMCS) reference implementation.

Install

python -m pip install -e ".[dev,api]"

If you only need core library features:

python -m pip install -e ".[dev]"

Adopt In 1 Hour

1. Create a SQLite store.
2. Append events through AMCSClient.
3. Read the memory root.
4. Verify the chain.
5. Optionally encrypt payload fields before append.

Minimal Append

from amcs import AMCSClient, SQLiteEventStore

store = SQLiteEventStore("./amcs.db")
client = AMCSClient(store=store, agent_id="agent-1")

result = client.append("interaction.append", {"message": "hello"})
print(result.sequence, result.event_hash, result.memory_root)

Verify Chain

from amcs import verify_chain

result = verify_chain(store, "agent-1")
assert result.ok

External Root Checkpoint (Optional)

Create a signed root receipt for external anchoring (for example: publish to an immutable log).

from amcs import b64encode, generate_keypair

private_key, public_key = generate_keypair()
checkpoint = client.create_root_checkpoint(
    signer_private_key_b64=b64encode(private_key),
    signer_kid="registry-main",
)
assert client.verify_root_checkpoint(
    checkpoint=checkpoint,
    signer_public_key_b64=b64encode(public_key),
)

Verification & Tamper Detection

For a full end-to-end tamper detection scenario, see:

• tests/test_sdk_append_verify.py

Encrypt Field (Optional)

from amcs import encrypt_field

enc = encrypt_field(
    b"secret",
    key,
    "kid-1",
    {"agent_id": "agent-1", "event_id": "evt-1", "event_type": "interaction.append"},
)

Canonical JSON

from amcs import canonical_bytes, canonical_dumps

event = {"b": 1, "a": 2}
text = canonical_dumps(event)  # {"a":2,"b":1}
data = canonical_bytes(event)  # UTF-8 bytes

Optional API Service

from amcs.api import create_app

app = create_app("./amcs.db")

The API dependencies are installed with:

python -m pip install -e ".[api]"

Examples

• examples/minimal_append.py
• examples/action_invoke.py
• examples/encrypted_interaction.py

Manual Acceptance Test (10 Minutes)

Run the human-legible acceptance test:

./scripts/manual_acceptance_test.sh

Detailed runbook:

• docs/manual-acceptance-test-10min.md