# Claude Co-work Substrate Memory

**Beta — stdio transport unverified in the Co-work sandbox.** The plugin format is verified against Anthropic's cached Co-work authoring skill, but its stdio MCP execution environment in Co-work's VM sandbox is not verified. A human must install the `.plugin`, open a Co-work session, and confirm `substrate_status` returns before support is claimed.

Substrate Memory gives Claude Co-work seven MCP tools for searching and recording organizational memory. Capture is skill-driven: the bundled skill directs Claude to search prior work before answering, remember durable user facts and decisions, and sync at natural session boundaries. Hooks are a best-effort bonus only and may never fire in Co-work.

## Install

1. Package the repository as a `.plugin` file as described in [docs/packaging.md](docs/packaging.md).
2. Install the `.plugin` file in Claude Co-work.
3. Set the environment variables below in the process that launches Co-work.
4. Start a session and run `substrate_status`.

## Configuration

Set these secrets in the process environment only:

```text
SUBSTRATE_API_URL=https://api.substrate.example
SUBSTRATE_API_KEY=...
```

`SUBSTRATE_API_KEY` is never written to a config file. Host config files are world-readable plaintext. `SUBSTRATE_PYTHON` optionally overrides the `python` executable used for the stdio server.

Sandbox consequences and mitigations:

1. A loopback `http://127.0.0.1` Substrate URL may not resolve from the Co-work sandbox; use an HTTPS URL.
2. `python` may not be on the sandbox `PATH`; set `SUBSTRATE_PYTHON` to an available executable.
3. `.mcp.json` also supports an `{"type":"http","url":...}` transport as an alternative when a hosted MCP endpoint is available.

## Tools

- `substrate_search` — search cited organizational memory cards.
- `substrate_read` — read a wiki page by path.
- `substrate_query` — ask for a cited synthesis.
- `substrate_ingest` — submit text for ingestion.
- `substrate_remember` — record a durable fact, decision, or preference.
- `substrate_sync` — flush the durable local spool.
- `substrate_status` — report content-free configuration and delivery status.

## Privacy boundary

The plugin reads API credentials from the process environment only, redacts captured text before persistence or transfer, and emits content-free operational diagnostics. It does not read Co-work transcripts; hook events contain only a session boundary signal. Report vulnerabilities through GitHub private security advisories.

See [BOUNDARY.md](BOUNDARY.md) and [SECURITY.md](SECURITY.md) for the public commitment and security policy.

## Repository map

- `skills/` — the primary Co-work capture instructions and tool reference.
- `src/claude_cowork_memory/` — Co-work runtime, MCP server, hook, and CLI.
- `src/substrate_capture/` — frozen shared client, redaction, spool, event, and MCP core.
- `hooks/` — best-effort Stop and SessionEnd integration.
- `tests/` — core and plugin contract tests.
- `docs/packaging.md` — `.plugin` creation instructions.

MIT © 2026 Sightline Technologies Inc.