Your first useful memory.

Use uv with Python 3.10+. This isolates the CLI from your project dependencies. You can use bare agentevo in place of the pinned npm launcher in the examples below.

uv tool install agentevo-sdk==0.2.9
agentevo init

Headless use needs one retained vault key through your secret manager. Never create a new key each time. Choose agentevo-sdk on PyPI or @agentevo-cli/agentevo on npm; unscoped names are other products. This guide uses published SDK/npm 0.2.9 (local 0.1.9, core 0.1.8). For diagnostics, run npx @agentevo-cli/agentevo@0.2.9 doctor. Doctor checks local configuration and does not attest host interception.

Initialization creates local memory. Connecting a host is a separate reviewed action. Supported Claude Code integration requires Claude Code 2.1.295+ and a reviewed setup preview.

npx @agentevo-cli/agentevo@0.2.9 host setup claude-code

Read the proposed files, hooks and limits. Apply only the exact command and preview digest printed by the CLI when you accept that configuration. Re-preview after changes. Setup compiles Candidates and grants no host permissions. Selected test context, workflow execution and high-risk approval have additional policy/evidence requirements.

Use agentevo doctor to inspect configuration; actual host callbacks and a controlled host-action check are separate evidence. For a strict CI gate, review agentevo ci --help and prepare a nonempty pinned manifest.

Start with a completed Claude Code task in this project and working project tests. No session yet? Initialization still works: finish a small tested task, then return here. You can also explore the illustrative lifecycle first.

npx @agentevo-cli/agentevo@0.2.9 capture --latest
npx @agentevo-cli/agentevo@0.2.9 compile --latest
npx @agentevo-cli/agentevo@0.2.9 verify --latest --local --workdir .
npx @agentevo-cli/agentevo@0.2.9 promote --latest --to Verified --local
npx @agentevo-cli/agentevo@0.2.9 recall "fix flaky test" --capabilities Bash,Edit,Read
npx @agentevo-cli/agentevo@0.2.9 report

Replace the recall query with your task. Expected: capture stores events locally, compile creates Candidates, verification reports evidence, and eligible objects promote to Verified. Recall can return matching local objects; the report opens from agentevo-report.html. Empty recall is a valid result, not a reason to invent a match.

Review the declared commands before verification: replay runs tests in your working copy and is not sandboxed. Inspect current_replay, integrity and task correctness separately. Interactive exit zero can contain failed or inconclusive evidence; a Verified object is not independently proven correct. Promotion refuses unmet gates.

npx @agentevo-cli/agentevo@0.2.9 capture --adapter codex ./session.jsonl

Local recall in an initialized project works without login or upload. The console displays authenticated cloud activity. To enable searchable sync, review the Terms and Privacy Policy, create an appropriate API key in the console, then run these commands only if you intend that consent and upload:

npx @agentevo-cli/agentevo@0.2.9 login
npx @agentevo-cli/agentevo@0.2.9 sync mode --set searchable --terms-version 2026-09-21 --yes
npx @agentevo-cli/agentevo@0.2.9 sync push
npx @agentevo-cli/agentevo@0.2.9 recall "fix flaky test" --capabilities Bash,Edit,Read --cloud

Login checks the hosted API before storing credentials in the OS keychain. Searchable sync sends minimized signed objects; explicit cloud recall sends its query and selected sanitized context. Optional BYOK embeddings contact the selected model provider and can incur its charges. Read the data boundary before enabling either.

Objects pulled to another machine arrive as Candidates. Verify them in that machine's project before promotion and local recall. Offline peers learn cloud revocation changes on later receipt/sync.

Check the exact package name and agentevo --version. Open a new terminal after tool installation, or use the pinned npm launcher. For uv PATH instructions, run uv tool update-shell and review its output.

Retain the original OS-keychain key. For headless use configure one persistent vault key through private secret management; a new random key on every run cannot open existing memory. An unconfigured host is separate from local readiness: follow the reviewed preview above if you want integration.

Run from the initialized project where the session occurred. Claude latest selection is project-bound. For Beta adapters provide a supported export explicitly. Compile does not manufacture reusable evidence from every run. Recall withholds ineligible objects and reports hints; inspect those before verifying/promoting the exact object.

Check the JSON and supported test command, dependencies and --workdir .. Review and run your project tests first, then reverify. Do not treat interactive exit zero as a strict CI pass or force a trust state to remove the warning.

Initialized local recall keeps working. Explicit cloud requests can fail or pause at quota; inspect their error/reset guidance. Export, deletion and containment have their documented exceptions. Review the workspace sync mode before retrying upload, and check current state before repeating a timed-out mutation.

Start with the working files you already keep. For eligible historical work, SDK 0.2.9 adds experience.read and agentevo_sdk.reuse.try_reuse. The host supplies its existing approved current-contract sandbox validator. At most three candidates are validated; a passing implementation is rechecked for eligibility before the host stages it through normal permissions and skips generation. A miss or failed test continues normal task work.

Installing the CLI alone does not enable this orchestration. The trusted callback binds the current task/tests/environment to a contract SHA256 and actual validation receipt. Cleanup failures stop the host. A partial Edit remains a fragment; a passing old lesson alone does not grant action authority.

An explicit read returns bounded untrusted C3 code, which your coding host may forward to its model provider. Review that handling and current tests before use. A memory hit alone is not a saved request. The complete repeat-work study includes paid cold acquisition, failures and the plain file-cache control; it does not establish customer net ROI or human time saved.

npx @agentevo-cli/agentevo@0.2.9 experience read --help

The published SDK README describes the host API and its limits. This optional integration adds no prerequisite to the local initialization above.