Agent Memory (Local-First) #

This system provides fast local working memory with optional remote sync.

Goals #

• Keep working-memory reads local and fast.
• Avoid plaintext remote transcript storage.
• Support continuity across laptops with remember lineage.
• Keep Docker/devcontainer rebuilds smooth (no new npm deps).

Local Store #

Default location:

• ~/.ac-agent-memory

Override:

• AGENT_MEMORY_HOME=/some/path

Layout:

• sessions/*.json - session metadata
• events/*.ndjson - encrypted append-only events
• checkpoints/*.ndjson - redacted checkpoints
• queue/outbound.ndjson - remote sync queue (optional)
• device-id - stable local device id
• key.bin - local AES key (if AGENT_MEMORY_KEY is not provided)

Security #

• Event payloads are encrypted locally with AES-256-GCM.
• Redaction runs for previews/summaries before indexing/sync.
• Raw plaintext is not written to remote by default.

Optional key management:

• AGENT_MEMORY_KEY=base64:<32-byte-key>
• or AGENT_MEMORY_KEY=<hex64>

If unset, a local key file is generated automatically.

CLI #

# List sessions
node memory/cli.mjs list

# Log event (from JSON stdin)
echo '{"provider":"codex","role":"user","text":"hello"}' | node memory/cli.mjs event --session my-session

# Manual checkpoint
node memory/cli.mjs checkpoint --session my-session --reason manual

# Continue by lineage (new session seeded from checkpoint)
node memory/cli.mjs remember --from my-session

# Health/status
node memory/cli.mjs doctor

# Print reproducible env profile (for other machines)
node memory/cli.mjs profile --include-key --exports

NPM shortcuts:

• npm run agent-memory:doctor
• npm run agent-memory:profile
• npm run agent-memory:set-device -- --id thinkpad-x1-main
• npm run agent-memory:sync-codex
• npm run agent-memory:install-hooks

Fish ac-* shortcuts (devcontainer):

• ac-memory-list -- --limit 25
• ac-memory-remember -- --from <session-id>
• ac-memory-hooks
• ac-memory-sync
• ac-memory-flush

Hook Integration #

• .claude/settings.json already calls memory/hook.mjs on UserPromptSubmit.
• memory/hook.mjs writes each hook event to local encrypted memory.
• .githooks/post-commit logs a commit event, imports recent Codex prompts, and flushes remote queue.
• Install repo hooks once with: npm run agent-memory:install-hooks

Multi-Vendor + Multi-Machine #

For Codex + Claude side-by-side across 2-3 machines, use shared key + per-machine device id:

# Shared across all your machines (same value everywhere)
export AGENT_MEMORY_KEY="base64:<32-byte-key>"

# Unique per machine/container
export AGENT_DEVICE_ID="thinkpad-x1-main"

# Optional defaults per terminal/session
export AGENT_MEMORY_PROJECT="aesthetic-computer"
export AGENT_MEMORY_PROVIDER="claude"   # or codex
export AGENT_MEMORY_TICKET="ticket-4821"

Recommended session id convention when multiple tickets are active:

<ticket>-<provider>-<device>-<short-ts>

Examples:

• ticket-4821-claude-thinkpadx1-20260312t1940
• ticket-4821-codex-thinkpadp1-20260312t1942

Side-by-side quick commands:

# Claude terminal
AGENT_MEMORY_PROVIDER=claude AGENT_SESSION_ID=ticket-4821-claude-thinkpadx1-20260312t1940 node memory/cli.mjs event --text "start"

# Codex terminal
AGENT_MEMORY_PROVIDER=codex AGENT_SESSION_ID=ticket-4821-codex-thinkpadp1-20260312t1942 node memory/cli.mjs event --text "start"

Reproducible setup flow (recommended):

1. On your primary machine, generate and print a portable profile: node memory/cli.mjs profile --include-key --exports
2. Copy those exports into your private machine env (.devcontainer/envs/devcontainer.env or shell profile).
3. On each machine, set a unique device id: npm run agent-memory:set-device -- --id <unique-machine-id>
4. Validate with: npm run agent-memory:doctor

Template for Docker/devcontainer env wiring:

• .devcontainer/envs/agent-memory.env.example
• .devcontainer/devcontainer.json now forwards AGENT_MEMORY_* vars from host localEnv

Optional Remote Sync #

Remote sync is disabled by default.

Enable queue + flush:

export AGENT_MEMORY_REMOTE_ENABLED=true
export AGENT_MEMORY_REMOTE_URL="https://aesthetic.computer/api/agent-memory-ingest"
export AGENT_MEMORY_REMOTE_TOKEN="<token>"

Flush queued records:

node memory/cli.mjs flush-remote

Remote ingest endpoint:

• system/netlify/functions/agent-memory-ingest.mjs

Recommended for siphoned database setup:

• AGENT_MEMORY_MONGODB_CONNECTION_STRING
• AGENT_MEMORY_MONGODB_NAME
• AGENT_MEMORY_SECRET_ID (defaults to agent-memory)

Store ingest auth token in Mongo secrets collection (same pattern as other services):

• _id: "agent-memory" (or your AGENT_MEMORY_SECRET_ID)
• field: ingestToken (also accepts token or remoteToken)

Docker / Rebuild Notes #

• Uses built-in Node modules only (crypto, fs, etc.).
• No package-lock changes required.
• No Dockerfile changes required for basic local-first mode.