Tacit

Tacit is a browser-memory MVP. It records browser sessions, stores raw rrweb evidence, projects rich bmem:* custom events into compact episode input, and sends memory-grade episodes to Zep while keeping local provenance back to sessions, pages, events, and node context.

Architecture

apps/
  extension/        Chrome side panel, rrweb capture, custom events, idb outbox
  backend/          Express capture API, Postgres raw storage, debug/replay API
  memory-service/   polling processor, projection, AI SDK episode builder, Zep ingestion

packages/
  capture-schema/   shared Zod contracts for capture/session/rrweb/custom events

Key dependencies:

• rrweb records replayable browser evidence.
• idb backs the extension upload outbox.
• Express, pg, and Zod keep the capture API small.
• The AI SDK creates structured episode drafts.
• Zep owns long-term graph memory.

Runtime Flow

Extension capture on
  -> POST /api/v1/capture/sessions/start
  -> rrweb native events + bmem custom events
  -> IndexedDB outbox
  -> POST /api/v1/capture/rrweb-batch
  -> POST /api/v1/capture/sessions/:id/end
  -> pending session_processing_run
  -> memory-service projects bmem events
  -> AI SDK builds ZepEpisodeDraft[]
  -> Zep graph.add
  -> local zep_episode_refs + memory_evidence_refs

API

GET  /api/v1/health
POST /api/v1/capture/sessions/start
POST /api/v1/capture/sessions/:sessionId/end
POST /api/v1/capture/rrweb-batch
GET  /api/v1/debug/sessions/:sessionId
GET  /api/v1/debug/sessions/:sessionId/rrweb
GET  /api/v1/debug/processing-runs/:runId
GET  /api/v1/debug/zep-episodes/:sessionId

Local Setup

Prerequisites:

• Node.js 20 or newer
• pnpm 11
• Docker
• Chrome or another Chromium-based browser

The backend and memory service use Postgres when STORAGE_DRIVER=postgres. The memory service polls DATABASE_URL, so Postgres must be running before the service starts.

1. Install dependencies:

pnpm install

2. Create a local environment file:

cp .env.example .env

Set the local development values:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/tacit
STORAGE_DRIVER=postgres
MEMORY_EPISODE_BUILDER=mock
ZEP_INGESTION=mock

Use MEMORY_EPISODE_BUILDER=ai only when AI_GATEWAY_API_KEY is set. Use ZEP_INGESTION=zep only when ZEP_API_KEY is set.

3. Start Postgres with Docker:

docker run --name tacit-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=tacit \
  -p 5432:5432 \
  -d postgres:16

If the container already exists, start it instead:

docker start tacit-postgres

4. Run the database migrations:

pnpm --filter @repo/backend test:migrations:dist

5. Start the development processes from the repository root:

pnpm run dev

This starts the backend, memory service, and extension build watcher through Turbo.

6. Load the Chrome extension:

1. Wait for apps/extension/dist to exist.
2. Open chrome://extensions.
3. Enable Developer mode.
4. Click Load unpacked.
5. Select apps/extension/dist.
6. Copy the extension ID shown by Chrome.
7. In .env, replace the placeholder in CORS_ALLOWED_ORIGINS with chrome-extension://<extension-id>.
8. Restart the backend dev process so it reads the updated .env file.

After loading the extension, open the Tacit side panel from Chrome and start capture from there.

Testing

Unit and contract tests cover the shared capture schemas, extension capture helpers, backend raw-evidence API, and memory-service projection/Zep provenance path:

pnpm test

The full browser-memory e2e suite loads the Chrome extension in Playwright, captures real browser behavior, stores rrweb evidence, runs the memory service, and verifies projected graph episode provenance. It uses a dedicated test database on port 5433:

docker run --name tacit-postgres-test \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=postgres \
  -p 5433:5432 \
  -d postgres:16

If the container already exists:

docker start tacit-postgres-test

Run the extension e2e suite:

pnpm --filter @repo/e2e test:e2e

The e2e suite defaults to postgres://postgres:postgres@localhost:5433/tacit_test and refuses non-test database names unless explicitly overridden.