# Trace v0.5.0 — easier connections Trace's public website demonstrates and distributes the product. Actual checks run in the local engine. The ordinary website URL of your product is not enough: Trace needs application callbacks or an explicit staging HTTP contract. ## Choose how to start - **Windows x64:** download `TraceSetup-0.5.0.exe`, open it and confirm the per-user installation. It includes the Python runtime and MCP support. Use SynapSoul Trace in the Start menu. The local dashboard opens automatically. The console executable `Trace-0.5.0.exe` is also available for portable/CLI use. These binaries are unsigned; this release does not include code signing. Do not bypass a browser or operating-system security warning automatically. - **Python 3.11+:** install the supplied wheel with `python -m pip install /path/to/synapsoul_trace-0.5.0-py3-none-any.whl`, then run `trace serve --open-browser`. The source ZIP launchers remain supported. `trace doctor` checks prerequisites without installing anything. - **Docker:** extract the source ZIP and run `docker compose up --build -d`; open `http://127.0.0.1:8765`. `docker compose down` stops the engine without removing the named evidence volume. The container uses a non-root user; publish its port on loopback only. For an alternative published port, set `TRACE_PUBLIC_PORT` to that host port. Set `TRACE_CONTAINER_NAME` to the actual container name when not using the supplied Compose file, so downloaded host MCP configuration targets the right container. Windows application files and evidence are separate. Evidence defaults to `%LOCALAPPDATA%/SynapSoul/Trace/data` for a double-click launch. Use **Connect & integrate → Stop this local engine** before uninstalling. Run the installed `TraceSetup.exe --uninstall` to remove the application files and Start-menu shortcut. Evidence and connections are retained. No administrator access is required. Installer testing uses an isolated destination and no Start-menu mutation; the release is not signed or certified across all Windows installations. ## Start with the local Mem0 sample Open **Connect & integrate**. Review the optional-dependency notice, allow installation, and choose **Install and start local sample**. Trace creates a dedicated virtual environment, installs Mem0 2.2.1 / Qdrant client 1.18.0, starts its owned gateway, waits for readiness, and fills the staging URL when you choose **Review sample coverage**. Setup needs internet and a separate Python 3.11–3.13 interpreter, even in the frozen Windows app. Subsequent starts reuse the environment. Diagnostics are in `/managed-mem0/setup.log`. This is a Trace-owned example application, not your existing Mem0 system or a hosted account. Active memories and vectors are two views of one Qdrant-backed store. The example has no answer cache; audit history and ID mapping are retained and excluded. No LLM inference or paid API key is used. Stopping Trace stops the owned sample process. Unfinished synthetic cleanup remains visible in evidence. ## Connect your own application ### Python callbacks Download the Python starter in the local dashboard. `TraceAdapter` accepts `ingest(namespace,id,text)`, `query(namespace,query)`, `inventory(namespace)` and `delete(namespace,ids)` callbacks. Return protocol dictionaries. `serve_adapter(adapter, port=8879)` exposes them on loopback; `adapter.wsgi(token_env=...)` can be mounted under a staging web server using full `/trace/v1/*` paths. The WSGI form relies on the application's hosting and TLS policy; use a token and expose only in staging. Bind existing Mem0 with `mem0_adapter(memory)` from `synapsoul_trace.integrations.mem0`. The helper preserves fresh Trace namespaces and issued IDs. Tested scope: Mem0 2.2.1 with Qdrant backing, infer=False, active memories and fully scrolled vector points. Excluded: history, graph memory, any separate answer cache, model inference and physical erasure. The helper initializes Mem0's optional cold NLP path before serving; it does not create records during setup. Declare cache excluded only when there is no cache in this contract. ### JavaScript callbacks Download the JavaScript starter and run `node server.mjs` for a disposable example. Replace its four async hooks with your actual staging functions. `createTraceServer` supports a standalone Node HTTP server; `createTraceHandler` can be mounted before an existing server's JSON parser. Node 20+; no runtime dependencies. A local npm tarball is supplied, but the package is not published to npm. Preserve namespace isolation, supplied IDs and the unrelated control. A database-only adapter checks the database path, not your application's end-to-end deletion behavior. ### Existing HTTP APIs Import OpenAPI 3 **JSON** in the dashboard to list available routes. Choose each operation and edit the mapping JSON to match the application's request and response fields. No external `$ref` is fetched. OpenAPI cannot prove deletion semantics or inventory completeness. Download the validated mapping, then run `trace adapter-serve --mapping trace.mapping.json --port 8879`. Connect `http://127.0.0.1:8879/trace/v1` as a custom adapter. Mappings support static paths, POST/PUT/PATCH/DELETE JSON bodies, scalar GET query parameters for read operations, and HTTP 200 JSON responses. Request variables are `$namespace`, `$id`, `$text`, `$query`, `$ids`. Responses use dotted object-field paths. Inventory completeness and source/vector counts must come from upstream fields; missing fields never default to zero. An absent cache may explicitly map to `{"literal":0}` only with cache coverage excluded. Path parameters, streaming results, non-200 success responses and complex pagination require a callback adapter. Keep upstream credentials in the named environment variable, never in mapping JSON. ## Review → run → understand The inventory-only connection check makes no synthetic writes. Review source, vectors, cache, history, workers, test effects and the observation window. Allow test writes only after reviewing. Outcomes, coverage and cleanup stay separate. A missing observation is inconclusive, not proof that data was removed. A PASS covers only this contract and time window. ## Export → import → CI Export saved connections and regressions from **Connect & integrate**. The JSON bundle includes endpoint URLs, declared scope, token **variable names**, and saved assertions, but no environment secret values or evidence database. Review endpoint URLs before sharing. Bundles use digests for consistency, not trusted signatures. On another machine, choose the bundle, inspect its destinations, acknowledge the review, and import. No endpoints are contacted by import. Conflicts with existing immutable records reject the entire import. CLI equivalents: ```text trace --data-dir .trace-ci connections-import --file trace.connections.json --preview trace --data-dir .trace-ci connections-import --file trace.connections.json trace --data-dir .trace-ci external-ci --regression SAVED_ID --output reports/trace-ci.json ``` Save a completed confirmed failure before generating CI. **Download GitHub Actions workflow** downloads one ZIP containing a workflow and matching bundle. Put the workflow under `.github/workflows/` and the reviewed bundle at the repository root. The workflow installs the release wheel, imports definitions and replays exact saved contracts; it uploads evidence even when checks fail. Configure required token names in repository secrets. Ensure the runner can reach your staging adapter. A loopback target needs a runner-local service or self-hosted runner; a hosted runner cannot reach your laptop's localhost. Exit codes remain 0 PASS, 1 FAIL, 2 INCONCLUSIVE/configuration error. The workflow template is generated and CLI-tested; execution on a user's GitHub repository is not part of this local release verification. ## MCP Download the machine-specific MCP JSON from **Connect & integrate**, add it to your MCP client and restart that client. Source/wheel installs require the optional `[mcp]` extra. The Windows app includes it. Docker configuration uses `docker exec -i`, without a TTY. The same 15 tools remain available; MCP cannot import targets, install dependencies or retarget URLs. Register and review targets locally first. ## Accessibility The new flow includes explicit labels, keyboard-operable buttons, visible focus styles, status announcements, main-content skip navigation, one local font, and responsive layouts. This is not a claim of a formal accessibility audit.