Skip to main content
Glama
AI Agent History RAG MCP Server

AI Agent History RAG MCP Server

by velenzaboc
README.md
# AI Agent History RAG

AI Agent History RAG is a native Go daemon and MCP proxy for searchable history
from Claude Code, Codex, Gemini, Antigravity, ChatGPT exports, and Claude app
exports. Production storage is Cloud Spanner with a registered Vertex embedding
model. The daemon has no local-storage or unauthenticated production mode.

## Supported native entrypoints

| Platform | Operator entrypoint | Lifecycle |
|---|---|---|
| Container | `history-ragd start --config /app/history-ragd.json` | Docker owns process restart; `/live` is its healthcheck. |
| macOS | `scripts/install-launchd.sh` | Per-user LaunchAgent runs `history-ragd supervise`. |
| Linux | `scripts/install-systemd.sh` | Per-user systemd unit runs `history-ragd supervise`. |
| Windows | `scripts/install-windows.ps1` | Per-user logon task runs `history-ragd.exe supervise`. |
| MCP | `scripts/history-rag-mcp-native.sh` | Authenticated STDIO proxy to the loopback daemon. |

The repository's Compose file is retained as a compatibility artifact and is
not a supported native production operator entrypoint. Use the Dockerfile or a
platform installer until that artifact is separately migrated.

## Build

```bash
go build -o bin/history-ragd ./cmd/history-ragd
go test ./...
```

For a Windows binary from another platform:

```bash
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o bin/history-ragd.exe ./cmd/history-ragd
```

## Production contract

Every service installer validates the following values before registering a
native process. Deployment identities are inputs; never place real values in
repository files.

```text
CLAUDE_HISTORY_RAG_RUNTIME_CONTRACT=production
CLAUDE_HISTORY_RAG_STORAGE_BACKEND=spanner
CLAUDE_HISTORY_RAG_SPANNER_PROJECT=<project>
CLAUDE_HISTORY_RAG_SPANNER_INSTANCE=<instance>
CLAUDE_HISTORY_RAG_SPANNER_DATABASE=<database>
CLAUDE_HISTORY_RAG_SPANNER_EMBEDDING_MODE=spanner
CLAUDE_HISTORY_RAG_SPANNER_EMBEDDING_MODEL_ID=ConversationEmbeddingModel
CLAUDE_HISTORY_RAG_EMBEDDING_PROVIDER=vertex
CLAUDE_HISTORY_RAG_EMBEDDING_MODEL=gemini-embedding-001
CLAUDE_HISTORY_RAG_EMBEDDING_DIMENSION=3072
CLAUDE_HISTORY_RAG_STATUS_SERVER_HOST=127.0.0.1
CLAUDE_HISTORY_RAG_STATUS_SERVER_PORT=4680
CLAUDE_HISTORY_RAG_CREDENTIALS_SOURCE=application_default
CLAUDE_HISTORY_RAG_CREDENTIALS_PROFILE=impersonated_service_account
CLAUDE_HISTORY_RAG_CREDENTIALS_IDENTITY=<service-account-email>
CLAUDE_HISTORY_RAG_SERVER_PSK=<bearer-secret>
```

The host runtime uses the well-known, owner-protected impersonated ADC carrier.
Credential-file overrides, emulator configuration, and ambient Cloud SDK
configuration are rejected. In particular, leave `GOOGLE_APPLICATION_CREDENTIALS`,
`CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE`, `CLOUDSDK_CONFIG`, and
`SPANNER_EMULATOR_HOST` unset.

The carrier may retain the legacy `authorized_user` source or use a
device-bound `service_account` source. The latter is accepted only inside the
validated impersonation carrier; its target identity, scope, quota project,
source shape, and owner-only file ACL are checked before any Google client is
constructed. Do not commit a carrier, private key, refresh token, or machine
path to this repository.

## Source roots

The daemon watches exactly these six source families. Platform installers create
missing directories and generate owner-protected native configuration.

| Source | Default root |
|---|---|
| Claude Code | `~/.claude/projects` |
| Codex | `~/.codex/sessions` |
| Gemini | `~/.gemini/tmp` |
| Antigravity | `~/.gemini/antigravity` |
| ChatGPT export | `~/.claude-history-rag/imports/chatgpt` |
| Claude app export | `~/.claude-history-rag/imports/claude-app` |

ChatGPT and Claude app exports belong in their respective drop folders. The
watcher preserves source identity and rejects unsafe path changes.

Native workstation deployments pin eight roots: the six defaults above plus
stable Claude and Codex provider-profile parent directories. This lets newly
created profiles become visible without replacing the persisted root set;
non-transcript credential JSON remains outside the registry's source grammar.

On first enablement, the daemon records every already-present recognized source
path as a permanent exclusion and persists a per-host cutoff before it can
upload anything. Only complete conversations whose source-record timestamps are
at or after that cutoff are captured. Existing paths, copied older sessions,
and records without provable source timestamps are never backfilled.

## Container

Copy `.env.docker.example` to a private environment file, replace each
placeholder, then build and run the native image:

```bash
docker build --tag history-ragd:local .
docker run --rm --env-file .env.docker -p 4680:4680 history-ragd:local
```

The container binds `0.0.0.0:4680` only inside its network namespace and
requires authentication. Its Docker healthcheck calls `/live`; it does not
pretend a missing Spanner dependency is ready. Mount persistent source and state
volumes when operating beyond a smoke test.

## Host service installation

Every Velenza workstation maps its Meridian root at `~/Meridian` (`$HOME/Meridian`) and checks out this repository at `~/Meridian/repos/ai-agent-history-rag-mcp` with the compiled binary at `~/Meridian/repos/ai-agent-history-rag-mcp/bin/history-ragd`. Each workstation authenticates directly as its own `kopia-<host>@jeeves-486102.iam.gserviceaccount.com` identity from `~/.config/no13-backup/kopia-<host>.json` under `CLAUDE_HISTORY_RAG_CREDENTIALS_PROFILE=device_service_account` (accepting either a `service_account` key or an `external_account` X.509 certificate config without a synthetic `credential-home` directory or per-host flags).

Host ingestion services bind only `127.0.0.1:4680`; do not open that listener to the
network. Build the binary first, export `CLAUDE_HISTORY_RAG_SERVER_PSK`, then install from `~/Meridian/repos/ai-agent-history-rag-mcp`.

### macOS

```bash
cd ~/Meridian/repos/ai-agent-history-rag-mcp
CLAUDE_HISTORY_RAG_SERVER_PSK="$CLAUDE_HISTORY_RAG_SERVER_PSK" HISTORY_RAGD_BIN="$PWD/bin/history-ragd" ./scripts/install-launchd.sh
./scripts/uninstall-launchd.sh
```

See [launchd operator notes](docs/LAUNCHD_NATIVE.md).

### Linux

```bash
cd ~/Meridian/repos/ai-agent-history-rag-mcp
CLAUDE_HISTORY_RAG_SERVER_PSK="$CLAUDE_HISTORY_RAG_SERVER_PSK" HISTORY_RAGD_BIN="$PWD/bin/history-ragd" ./scripts/install-systemd.sh
./scripts/uninstall-systemd.sh
```

See [systemd operator notes](docs/SYSTEMD_NATIVE.md).

### Windows

```powershell
.\scripts\install-windows.ps1 -HistoryRagdPath "$PWD\bin\history-ragd.exe"
.\scripts\uninstall-windows.ps1
```

See [Windows operator notes](docs/WINDOWS_NATIVE.md). Windows Task Scheduler
validation requires a Windows host; the repository cross-build verifies only
that the native executable can be produced.

## Liveness and readiness

For search against an existing corpus, the explicit read-only host mode binds
`127.0.0.1:4681` and never starts a watcher. Set `CLAUDE_HISTORY_RAG_READ_ONLY=true`
and `CLAUDE_HISTORY_RAG_STATUS_SERVER_PORT=4681` in both daemon and MCP environments.
The `device_service_account` credential profile uses the existing device source
nested in private well-known ADC, bound to its exact source email, without
changing the carrier or impersonating its target. See [launchd setup](docs/LAUNCHD_NATIVE.md).
Read-only readiness reports storage only, with no ingestion claim.

`GET /live` is intentionally unauthenticated and answers only whether the
process listener is alive:

```bash
curl --fail http://127.0.0.1:4680/live
```

`GET /health` and `GET /status` require a bearer credential. They are readiness
checks: they return 200 only when both Spanner storage and the source watcher
are ready, otherwise 503. They never expose credentials or source paths.

```bash
curl --fail -H "Authorization: Bearer $CLAUDE_HISTORY_RAG_SERVER_PSK" \
  http://127.0.0.1:4680/health
```

## MCP proxy

Use the native STDIO proxy only after the loopback daemon is running with the
same production contract:

```bash
./scripts/history-rag-mcp-native.sh --validate-only
./scripts/history-rag-mcp-native.sh
```

## Troubleshooting

- `/live` fails: inspect the platform service manager and its native process.
- `/live` succeeds but `/health` returns 503: confirm Spanner reachability and
  that all six watcher roots are available to the service user.
- `/health` returns 401: supply the configured bearer secret; do not disable
  authentication to diagnose the issue.
- Installer rejects credentials: remove the forbidden ambient credential and
  emulator overrides, then verify the well-known impersonated ADC carrier.
- A source root is rejected: replace links with an owned real directory; the
  watcher intentionally refuses identity changes.

## Verification

```bash
./scripts/docs-native-contract.test.sh
go test -race ./internal/history/config ./internal/history/watch ./internal/history/api ./cmd/history-ragd
go vet ./...
go build ./...
go test ./...
```

The exact native contract and its bounded API surface are recorded in
[docs/NATIVE_COMPATIBILITY_CONTRACT.md](docs/NATIVE_COMPATIBILITY_CONTRACT.md).

### Certificate workload federation for a central search container

The explicit `workload_identity_federation` profile accepts the host's existing
X.509 `external_account` carrier selected process-locally by
`GOOGLE_APPLICATION_CREDENTIALS`. Set
`CLAUDE_HISTORY_RAG_CREDENTIALS_IDENTITY` to this container's scoped search identity,
and `CLAUDE_HISTORY_RAG_CREDENTIALS_AUDIENCE` to the exact provider resource URI.
The carrier's STS endpoint and service impersonation URL must be canonical
Google mTLS endpoints, with the carrier impersonation URL naming exactly the
declared search identity. Leave `CLAUDE_HISTORY_RAG_CREDENTIALS_BASE_IDENTITY`
unset; this profile never mints a shared host token. The certificate
configuration, certificate and key must
be explicit owner-only regular files; executable, file-token and ambient
certificate discovery are refused. The daemon uses the already-pinned modern
Google auth SDK for direct X.509 federation into the scoped target. Mount only
this container's own service carrier and certificate, with provider subject
access granted only to its corresponding search identity. Existing profiles
and local capture remain unchanged.

A read-only container may set `container_mode:true`, `read_only:true`,
`listen:"127.0.0.1:4681"`, `auth_enabled:true` and an empty `watch_roots` list.
It starts no watcher and requires an existing corpus. Preserve workstation
capture services and their forward-only cutoffs. Deploy the native daemon and
`scripts/history-rag-mcp-native.sh` side by side with bash, curl and jq. The proxy
calls the co-located daemon's `validate-workload-credentials` command before
serving MCP, sharing the Go credential validator without a shell credential
parser. This command validates local configuration only; it neither exchanges
tokens nor proves backend access. Apply the same environment to the daemon and
proxy. Keep runtime credential mounts read-only and PSK state private; never
embed credentials or PSKs in an image.

### Verification and delivery

During implementation and repair, run focused local checks for touched behavior
and direct dependencies on the working machine (any remote run uses
`/home/lab/Meridian/bin/velenza-remote-guard.py --host <arcserver1|arcserver2|arcserver4>`,
never `arcserver3`). When the complete submission candidate is ready and
independent acceptance passes, `.github/workflows/ci.yml` runs the full Go,
shell, and mutation test suite on `push`, `pull_request`, and `merge_group`.

TDQS

A4.1/5.0

Scored across 5 tools

Disambiguation4/5

Most tools have distinct purposes, but get_index_status and get_server_status overlap in indexing and database information, potentially causing confusion. Detailed descriptions help differentiate them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with underscores (get_* and search_*), making them predictable and clear.

Tool Count5/5

Five tools cover the necessary functionality for a RAG memory system without being too few or too many, earning each tool's place.

Completeness4/5

The tool set covers monitoring and search operations well, but lacks a tool to retrieve full conversation transcripts or manage indexing, which are minor gaps.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues