> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caveman.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Caveman Local Tools: Memory, Browser, Shrink, and MCP

> Use Caveman's local MCP server, memory store, browser bridge, output shrinker, and tool-catalog shrinker without a Caveman Cloud account.

Caveman ships local tools for recovery, memory, browser context, and large command output. They work without a Caveman account and run entirely on your machine.

## MCP server

Register the recovery server with detected agents:

```bash theme={"dark"}
caveman tools mcp install
```

Run `caveman tools mcp uninstall` to remove registration. The direct server binary, `caveman-mcp`, communicates over standard input and output.

It exposes five tool classes:

| Tool | Purpose |
| - | - |
| Compress | Reduce eligible context and return recovery reference |
| Retrieve | Fetch exact source for a recovery handle |
| Stats | Read local compression statistics |
| TOON encode | Encode supported structured input |
| TOON decode | Decode and validate TOON input |

MCP transport is local process I/O, and the host agent decides when tools can be called. Configure its tool permissions as narrowly as possible.

### Installing via npx

For Claude Code, add the MCP server to your configuration:

```json theme={"dark"}
{
  "mcpServers": {
    "caveman": { "command": "npx", "args": ["-y", "caveman-mcp"] }
  }
}
```

The launcher downloads a matching binary on first run, verifies key-signed checksum manifest plus artifact SHA-256, and caches it under `~/.caveman/bin`. No Go toolchain or global Caveman install is required. To use an existing reviewed binary instead:

```bash theme={"dark"}
CAVEMAN_MCP_BIN=/path/to/caveman-mcp npx caveman-mcp
```

## Cavemem

Cavemem stores durable project facts in SQLite and retrieves them with local BM25 text ranking.

Main operations:

```bash theme={"dark"}
caveman tools mem remember "fact"
caveman tools mem recall "query"
caveman tools mem supersede <id> "replacement"
caveman tools mem history <id>
caveman tools mem forget <id>
```

Recall returns current facts by default and has a default inferred-token budget of 2,000. Superseded history remains available for inspection. Recalled compact records can include recovery references to exact stored source.

Memory is local persistence, not model training. A remembered statement can be wrong or stale; source and supersession metadata help callers judge it.

Build standalone binary:

```bash theme={"dark"}
go build -o cavemem ./mem/cmd/cavemem
```

## Browser bridge

The browser bridge attaches to Chrome through Chrome DevTools Protocol. It captures an accessibility-tree representation, filters it by query, compresses it, and returns actionable element references.

```bash theme={"dark"}
caveman tools browse https://example.com "pricing"
caveman tools browse act '<reference>' click
caveman tools browse eval 'document.title'
caveman tools browse recover '<handle>'
caveman tools browse close
```

Snapshots avoid screenshots when semantic structure is enough. Recovery keeps exact captured source available. Browser actions and JavaScript evaluation can change page or account state; host permission policy should distinguish read and write operations.

Build bridge:

```bash theme={"dark"}
go build ./browse/cmd/caveman-browse
```

Run as MCP server:

```bash theme={"dark"}
caveman-browse
```

Direct CLI helper:

```bash theme={"dark"}
caveman-browse snapshot http://127.0.0.1:3000
caveman-browse snapshot http://127.0.0.1:3000 "save settings"
caveman-browse act <uid> click
caveman-browse recover <handle>
caveman-browse close
```

Direct commands share one detached, isolated Chrome until `close`; first use creates profile and CCR directories. Actions report `settled:false` until another focused snapshot proves state. Navigation permits `http(s)`, `about:blank`, and bounded `data:text/html` but rejects local files and privileged schemes.

## Output shrinker

The output shrinker parses large command and tool results, keeps high-signal structure, and stores full source in CCR. It is useful for compiler logs, test output, diffs, search results, and terminal transcripts.

```bash theme={"dark"}
some-command | caveman tools shrink
caveman tools shrink -- go test ./...
```

Structural shrink input is capped at 32 MiB. CLI command capture uses a separate bounded limit, 8 MiB by default. Oversized input is rejected or handled by caller policy; it is not silently treated as complete.

Shrinker must preserve error class, exit status, relevant paths, and recovery handle. A short summary without those fields is not a safe replacement for debugging output.

## Tool-catalog shrinker

`caveman-shrink` specializes in MCP and OpenAI-style tool catalogs. It keeps tool names, parameters, enums, required fields, defaults, constants, and `$ref` targets while removing annotations and shortening long descriptions. Description reduction remains lossy and can change tool selection.

```bash theme={"dark"}
cat tools.json | caveman-shrink > tools.min.json
caveman-shrink lint tools.json
caveman-shrink recover <handle> > tools.original.json
```

Input cap is 32 MiB. Malformed or non-winning input passes through. Exact source must be committed to CCR before compact catalog and handle are emitted.

## Local storage

Local proxy and tools commonly use these paths:

```text theme={"dark"}
~/.caveman/caveman.db
~/.caveman/ccr.db
~/.caveman/mem/mem.db
~/.caveman/mem/ccr.db
~/.caveman/caveman.yaml
~/.caveman-cloud/config.json
```

Project overlays use `./.caveman/config.json`. Back up or delete these files only with awareness that recovery handles and learned observations may stop resolving, along with local memory.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.