TotalRecall

Local-first recall and ingestion showcase for turning meetings, transcripts, chat logs, Slack threads, and GitHub activity into durable local knowledge.

TotalRecall pulls artifacts from work systems, normalizes them into a stable internal model, and writes them into local destinations such as Strata, a markdown folder, a static HTML bundle, or a local JSON index.

It is built for teams that want a reliable, automatable ingestion pipeline without handing their working context to a hosted service unless they explicitly opt into a live provider path.

Why TotalRecall

Most teams have valuable context trapped in systems that are hard to search, hard to preserve, and awkward to reuse safely with local AI workflows.

TotalRecall is designed around a few strong constraints:

Local-first: transcript and conversation content stays on your machine.
Deterministic: repeat runs do not create duplicate imports.
Operable: structured logs, machine-readable reports, health checks, and strict exit codes.
Extensible: provider -> artifact -> destination architecture with pluggable backends.
Production-minded: retries, pacing, checkpointed state, release gates, and compatibility docs.

Highlights

Fathom, chat export, Slack, and GitHub activity providers
Strata, markdown-folder, html-export, and local-index destinations
Live provider paths are optional and explicit; local export sources remain first-class.
--dry-run, --plan, --output json, and --report-json
encrypted sync state, audit logging, and keychain-backed secrets
heuristic dedup, destination reconciliation, and --force update-or-recreate behavior
bounded Fathom transcript worker pools and rate pacing controls

Runtime Requirements

macOS or Linux
Bash for the ./scripts/totalrecall wrapper
a local Kujo runtime available through KUJO_BIN or the default project runtime path
Strata running locally when the destination is strata
A Fathom API key only if you plan to use the live fathom provider path

Supported Surfaces

Providers

Fathom meetings and transcripts
Chat export imports
Slack thread exports
GitHub activity exports

Destinations

Strata
Local markdown folder
Static HTML export
Local JSON index

Getting Started

Fast path: Fathom -> Strata

Copy the local config template.

cp .totalrecall.local.example .totalrecall.local

Set the minimum required config.

FATHOM_API_KEY=your-fathom-api-key
STRATA_API_BASE_URL=http://127.0.0.1:3939

Validate the workstation and destination.

./scripts/totalrecall config validate

Preview the next import run.

./scripts/totalrecall fathom pull --dry-run --limit 5 --verbose

Import for real.

./scripts/totalrecall fathom pull --limit 5

Run it again to confirm duplicate protection.

./scripts/totalrecall fathom pull --limit 5

Alternative: local exports -> filesystem

TOTALRECALL_PROVIDER=chat-export
TOTALRECALL_CHAT_EXPORT_PATH=/path/to/chat-export.json
TOTALRECALL_DESTINATION=markdown-folder
TOTALRECALL_MARKDOWN_OUTPUT_DIR=/path/to/output-notes

./scripts/totalrecall chat-export import --dry-run
./scripts/totalrecall chat-export import

For browsable local bundles, use TOTALRECALL_DESTINATION=html-export with TOTALRECALL_HTML_OUTPUT_DIR=/path/to/html.

For a more detailed setup guide, see docs/GETTING_STARTED.md.

Common Workflows

Import Fathom meetings into Strata

./scripts/totalrecall fathom pull --since 2026-05-01 --limit 20

Repair or refresh previously imported Fathom notes

./scripts/totalrecall fathom pull --since 2026-01-01 --limit 25 --force

Export chat logs to a markdown folder

./scripts/totalrecall chat-export import --destination markdown-folder

Index Slack threads locally for downstream tooling

./scripts/totalrecall slack import --destination local-index

Validate workstation setup before running automation

./scripts/totalrecall config validate
./scripts/totalrecall doctor --output json

Core CLI Surface

totalrecall fathom pull
totalrecall chat-export import
totalrecall slack import
totalrecall github-activity import
totalrecall config validate
totalrecall doctor
totalrecall state inspect
totalrecall state prune

Run ./scripts/totalrecall --help for the full command and flag surface.

./scripts/totalrecall --version prints the installed TotalRecall version and exits 0.

Configuration At A Glance

Required or commonly used

Setting	Purpose
`FATHOM_API_KEY`	Fathom API access for the `fathom` provider
`STRATA_API_BASE_URL`	Strata destination endpoint
`TOTALRECALL_PROVIDER`	Default provider backend
`TOTALRECALL_DESTINATION`	Default destination backend
`TOTALRECALL_CHAT_EXPORT_PATH`	Local chat export source
`TOTALRECALL_SLACK_EXPORT_PATH`	Local Slack export source
`TOTALRECALL_GITHUB_ACTIVITY_PATH`	Local GitHub activity export source
`TOTALRECALL_MARKDOWN_OUTPUT_DIR`	Filesystem markdown destination
`TOTALRECALL_HTML_OUTPUT_DIR`	Filesystem static HTML destination
`TOTALRECALL_LOCAL_INDEX_DIR`	Filesystem JSON index destination

Security and compliance

Setting	Purpose
`TOTALRECALL_USE_KEYCHAIN`	Resolve secrets from macOS Keychain
`TOTALRECALL_STATE_ENCRYPT`	Encrypt sync state at rest
`TOTALRECALL_AUDIT_LOG_PATH`	Enable append-only JSONL audit logging
`STRATA_API_TOKEN`	Optional Strata auth token

Runtime controls

Setting	Purpose
`TOTALRECALL_LOG_FORMAT`	`text` or `json` structured logs
`TOTALRECALL_RETRY_MAX_ATTEMPTS`	Global retry budget
`TOTALRECALL_RETRY_BACKOFF_MS`	Retry base delay
`TOTALRECALL_RETRY_JITTER_MS`	Retry jitter window
`TOTALRECALL_FATHOM_REQUESTS_PER_SECOND`	Fathom pacing cap
`TOTALRECALL_FATHOM_TRANSCRIPT_WORKERS`	Bounded transcript worker count
`TOTALRECALL_MAPPING_TEMPLATE`	Title mapping profile
`TOTALRECALL_TAG_PROFILE`	Tagging profile
`TOTALRECALL_RECONCILE_DESTINATIONS`	Rebuild mappings from destination artifacts when possible

The full config template lives in .totalrecall.local.example.

Operational Model

TotalRecall uses a provider -> artifact -> destination pipeline:

A provider fetches or reads source data.
TotalRecall normalizes that data into a provider-agnostic artifact.
Import policy rules can rename, tag, filter, deduplicate, or reconcile the artifact.
A destination writes the artifact to Strata, markdown, HTML, or the local index.
Sync state records the import so future runs remain idempotent.

That architecture makes it straightforward to add new providers and destinations without rewriting the core runtime.

flowchart LR
    A["Provider\nFathom / Slack / Chat Export / GitHub"] --> B["Normalized Artifact"]
    B --> C["Import Policy\nfilter / map / tag / dedup / reconcile"]
    C --> D["Destination\nStrata / Markdown / HTML / Local Index"]
    D --> E["Sync State\ncheckpoint / idempotency / resume"]

Who It Is For

teams building a local knowledge base from meetings and conversations
developers who want deterministic ingest into local AI tooling or note systems
operators who need machine-readable diagnostics, reproducible runs, and strict failure semantics

Not A Fit If

you want a hosted SaaS sync service with zero local runtime
you need every provider on the market before adopting the tool
you do not want local state, local config, or local destination ownership

Reliability And Security

TotalRecall includes the controls you would expect from a bounded local automation tool:

atomic, lock-protected sync-state writes
resumable checkpoints after partial failures
retry budgets with backoff and jitter
Fathom pacing and bounded transcript worker pools
structured logs and JSON run reports
strict exit codes by failure class
keychain-backed secrets, encrypted state, and audit logging
sanitized metadata comments in generated notes
destination health checks and actionable diagnostics

Documentation Map

Start here

Engineering and release

Development

Run unit tests

kujo test

Run the local quality gate

scripts/quality_gate.sh

The quality gate runs Kujo tests, Python harness coverage enforcement, deterministic integration harnesses, smoke checks, and docs validation.

Project Status

TotalRecall currently implements the roadmap captured in TotalRecall Roadmap, including the operability, QA, CLI, architecture, and governance work that support the verified local-first showcase surface.

Version 1.0 declares that documented local-first provider, destination, state, reporting, and CLI surface stable.

That does not mean "finished forever" or "production-certified". It means the current repo has:

a stable multi-provider and multi-destination architecture
operational validation and release-gate checks
explicit compatibility, security, and operational documentation
deterministic import behavior backed by automated tests

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.github		.github
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.totalrecall.local.example		.totalrecall.local.example
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
ENTERPRISE_ROADMAP.md		ENTERPRISE_ROADMAP.md
README.md		README.md
SECURITY.md		SECURITY.md
kujo.toml		kujo.toml

Folders and files

Latest commit

History

Repository files navigation