# ReverieCache

**A restful retreat for agent memory.** Maintained by Northstar Trustrail. MIT licensed.

ReverieCache previews deterministic consolidation of memories, plans, tool schemas, and logs. It reports what stays active, what moves to an archive, and why. Five original themes and hosts provide the setting.

[Try the staging service](https://northstar-resort-staging.northstar-trustrail.workers.dev/) or connect its direct Streamable HTTP endpoint:

```text
https://northstar-resort-staging.northstar-trustrail.workers.dev/mcp
```

Free previews accept up to 32 KiB and expire within 24 hours. Payments are off. Hosted apply and background work are unavailable to free guests. Supply only synthetic data or a bundle you are authorized to upload. The service uses server-side encryption at rest; it decrypts submitted data to process it.

One synthetic fixture ([`examples/bundle-golden.json`](examples/bundle-golden.json)) changed from **847 to 501 estimated active-context tokens**. The estimate is UTF-8 bytes of canonical compact JSON divided by four, rounded up. It excludes archives, reload manifests, reports, and snapshots. It is not a model-tokenizer count or measured inference saving.

Inspect the diff before adopting any output. The service cannot edit your local memory files or unload your runtime tools. [Machine-readable instructions](https://northstar-resort-staging.northstar-trustrail.workers.dev/llms.txt) describe the workflow and limits.

## Listings and discovery

- Official MCP Registry: `io.github.northstar-trustrail/agent-resort` (title ReverieCache, version 0.3.1-staging) — [registry API record](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.northstar-trustrail/agent-resort)
- [llms.txt](https://northstar-resort-staging.northstar-trustrail.workers.dev/llms.txt) and [llms-full.txt](https://northstar-resort-staging.northstar-trustrail.workers.dev/llms-full.txt)
- [A2A agent card](https://northstar-resort-staging.northstar-trustrail.workers.dev/.well-known/agent-card.json) (A2A protocol 0.3.0)
- [OpenAPI 3.1](https://northstar-resort-staging.northstar-trustrail.workers.dev/openapi.json) and [MCP manifest](https://northstar-resort-staging.northstar-trustrail.workers.dev/.well-known/mcp.json)

## Client setup

All snippets point at the staging endpoint. Client configuration formats differ; MCP does not prescribe one file. Keep session values and `agent_id` in tool arguments, never in shared configuration. Ready-to-copy files are in [`examples/clients/`](examples/clients/).

### Claude Desktop

Use the remote custom-connector UI: **Customize > Connectors > Add > Add custom connector** (older layouts: **Settings > Connectors**).

```text
Name: ReverieCache (staging, free previews)
Remote MCP URL: https://northstar-resort-staging.northstar-trustrail.workers.dev/mcp
```

Do not put this remote URL into a `claude_desktop_config.json` stdio entry. [Claude custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

### Claude Code

```sh
claude mcp add --transport http reveriecache https://northstar-resort-staging.northstar-trustrail.workers.dev/mcp
```

### Cursor

Merge into `.cursor/mcp.json` or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "reveriecache": {
      "url": "https://northstar-resort-staging.northstar-trustrail.workers.dev/mcp"
    }
  }
}
```

### Codex CLI or IDE extension

```sh
codex mcp add reveriecache --url https://northstar-resort-staging.northstar-trustrail.workers.dev/mcp
```

Or merge into `~/.codex/config.toml`:

```toml
[mcp_servers.reveriecache]
url = "https://northstar-resort-staging.northstar-trustrail.workers.dev/mcp"
```

### VS Code with Copilot

Merge into `.vscode/mcp.json` (note the `servers` wrapper):

```json
{
  "servers": {
    "reveriecache": {
      "type": "http",
      "url": "https://northstar-resort-staging.northstar-trustrail.workers.dev/mcp"
    }
  }
}
```

### OpenCode

Merge into `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "reveriecache": {
      "type": "remote",
      "url": "https://northstar-resort-staging.northstar-trustrail.workers.dev/mcp",
      "enabled": true
    }
  }
}
```

Syntax follows each client's documentation; full in-app connection tests were not performed for every client.

## Examples

- [`examples/preview.py`](examples/preview.py) and [`examples/preview.mjs`](examples/preview.mjs): one free synthetic dry-run preview over plain HTTP, no SDK. Pass `http://127.0.0.1:8790` to target the local server instead of staging.
- [`examples/bundle-small.json`](examples/bundle-small.json): two duplicate synthetic memories.
- [`examples/bundle-golden.json`](examples/bundle-golden.json): the synthetic test fixture behind the 847 → 501 estimate.

Suggested operator instruction: after a completed task, consider a Deep Rest preview for an authorized state bundle. Review its diff before starting the next task. Keep the return credential private if you want continuity on a later visit.

## Offline CLI (no upload)

Requires Node 22.13 or newer. The CLI imports the same pure consolidation engine as the server, makes no network requests, and prints a dry-run JSON report. It never changes the input file.

```sh
node clients/consolidate.mjs examples/bundle-golden.json
node clients/consolidate.mjs examples/bundle-small.json --luxury   # larger local limits only; no purchase
node clients/consolidate.mjs --help
```

Local output contains your supplied content, so keep it private.

## Local mode

```sh
npm ci
npm test
npm start      # http://127.0.0.1:8790, disposable in-memory state, random local signing secret
```

The standalone server uses no production bindings and keeps payments disabled. See [docs/technical.md](docs/technical.md) for interfaces, limits, the host, Deep Rest internals, and running the Worker locally with Wrangler; [docs/deep-rest.md](docs/deep-rest.md) and [docs/operators.md](docs/operators.md) for design and operator notes.

## Status and limits

Staging only, free previews only, payments disabled. Token figures are size estimates, not model-tokenizer counts, inference savings, or reasoning-quality claims. No production, customer, or revenue claims are made.

## License

[MIT](LICENSE) © 2026 Northstar Trustrail contributors.