5.7 KiB

Raw Blame History

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>

Promote the import into a canonical store:

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

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.

5.7 KiB Raw Blame History