# AMCS-0.1

Agent Memory Canonicalization Standard (AMCS) reference implementation.

## Install

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

If you only need core library features:

```bash
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

```python
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

```python
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).

```python
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)

```python
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

```python
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

```python
from amcs.api import create_app

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

The API dependencies are installed with:

```bash
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:

```bash
./scripts/manual_acceptance_test.sh
```

Detailed runbook:
- `docs/manual-acceptance-test-10min.md`
