GroundRecall

GroundRecall is a local-first, provenance-aware knowledge substrate for human-reviewable and assistant-usable memory. It imports source material into a canonical store, supports review and promotion, exports assistant-neutral snapshots, and can generate assistant-specific bundles for tools such as Codex and Claude Code.

GroundRecall is intended for work where durable context matters:

• site, app, and service administration across sessions
• local/remote deployment memory with host-role distinctions
• research notes and grounded claim tracking
• legacy document normalization through doclift
• learner-facing workflows through Didactopus
• assistant handoff between Codex, Claude Code, and other file-aware tools

Current Features

• Import from llmwiki-style trees, plain notes, normalized doclift bundles, Didactopus packs, transcripts, PolyPaper projects, and specialized corpora.
• Normalize imports into artifacts, fragments, observations, claims, concepts, and relations.
• Lint and review import output before promotion.
• Promote reviewed records into a canonical GroundRecall store.
• Query by concept and export query bundles.
• Export assistant-neutral canonical snapshots.
• Export assistant-specific bundles:
  • Codex: SKILL.md plus codex_bundle.json
  • Claude Code: CLAUDE.md plus claude_code_bundle.json
• Export pack-ready query bundles for Didactopus.
• Initialize an assistant-neutral host/project memory protocol with groundrecall protocol-init.

Installation

From a checkout:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
groundrecall --help

For development:

.venv/bin/python -m pytest

The package also supports module invocation when working directly from source:

PYTHONPATH=src python -m groundrecall --help

Basic Workflow

Import a source:

groundrecall import /path/to/source --out-root .groundrecall/imports --mode quick

Lint the import:

groundrecall lint .groundrecall/imports/<import-id>

Review significant imports:

groundrecall review-server .groundrecall/imports/<import-id>

Promote the import into a canonical store:

groundrecall promote .groundrecall/imports/<import-id> .groundrecall/store --reviewer your-name

Promotion refuses imports with lint errors by default. Fix the source material, adapter, or review data first. If you intentionally need to preserve a flawed import for triage or recovery, use:

groundrecall promote .groundrecall/imports/<import-id> .groundrecall/store \
  --reviewer your-name \
  --allow-lint-errors

Warnings remain visible in the review queue but do not block promotion.

Inspect or query the store:

groundrecall inspect .groundrecall/store
groundrecall query .groundrecall/store channel-capacity

Export assistant-neutral data:

groundrecall export .groundrecall/store .groundrecall/exports/canonical

Export assistant-specific data:

groundrecall assistant-export .groundrecall/store codex .groundrecall/exports/codex
groundrecall assistant-export .groundrecall/store claude_code .groundrecall/exports/claude_code

Assistant-Neutral Host Protocol

GroundRecall can initialize a reusable memory pattern for a project or host:

groundrecall protocol-init /opt/www \
  --host-id local-dev \
  --host-role development \
  --assistant codex \
  --assistant claude_code

This creates:

• .groundrecall/README.md
• .groundrecall/source-notes/host-profile-<host-id>.md
• .groundrecall/local-inbox/
• .groundrecall/remote-inbox/
• ASSISTANT_PROJECT.md
• assistant bootstrap files such as CODEX_PROJECT.md and CLAUDE.md

Use --force only when you intend to overwrite existing bootstrap files.

For a two-host local/remote setup, each host should maintain its own GroundRecall store and exchange source notes or exports. Do not make both hosts write directly into the same mutable store.

See docs/assistant-protocol.md.

Suggested Workspace Layout

.groundrecall/
  source-notes/
  imports/
  store/
  exports/
    canonical/
    codex/
    claude_code/
  local-inbox/
  remote-inbox/

source-notes/ is where humans and assistants should leave durable Markdown notes. Those notes can later be imported and promoted.

Didactopus Bridge

GroundRecall can export a pack-ready groundrecall_query_bundle.json for a reviewed concept:

groundrecall export /path/to/groundrecall-store /tmp/groundrecall-export \
  --pack-ready-concept channel-capacity

The matching Didactopus bridge flow is:

didactopus doclift-bundle-groundrecall \
  /path/to/groundrecall-store \
  channel-capacity \
  /tmp/doclift-bundle \
  /tmp/didactopus-pack \
  --course-title "Example Course"

See docs/didactopus-bridge.md.

Use Cases

GroundRecall is useful when the same project may be touched by different assistants, at different times, or on different hosts:

• A local development host and a remote production host both need operational memory.
• Codex performs a code change locally, then Claude Code investigates a service failure remotely.
• A WordPress or Forgejo service needs routing, backup, deployment, and recovery notes that survive across sessions.
• A research corpus needs grounded claims, citations, source provenance, and review state.
• Legacy office documents need doclift normalization before becoming searchable assistant context.

Safety Rules

• Store where secrets live, not secret values.
• Keep host-specific facts labeled by host and role.
• Treat production and mixed hosts as higher risk than development hosts.
• Prefer source-note/export replication between hosts over shared mutable stores.
• Commit code/config changes separately from generated GroundRecall exports unless the export is intentionally part of the deliverable.

Documentation

• docs/quickstart.md
• docs/assistant-protocol.md
• docs/architecture.md
• docs/didactopus-bridge.md
• docs/llmwiki-import.md
• docs/sync-roadmap.md