Memory & Vault¶

gald3r has two related-but-distinct knowledge surfaces: scoped memory records (small, structured facts an agent should remember across sessions) and the vault (a full searchable knowledge base built from docs, repos, and web pages you feed it). This page covers both.

Scoped memory records¶

gald3r memory add --help

Record a new scoped memory record

Flags:
  -b, --body string       The memory content itself.
  -c, --confidence int    1-10 confidence rubric (default 5).
      --expires string    ISO YYYY-MM-DD date after which this record is stale.
      --scope string      user | project | workspace | team | company | client
      --source string     Free-text provenance note.
      --tags string       Comma-separated freeform tags.
      --type string       fact | decision | preference | procedure | gotcha | reference | episodic

(Real --help output, trimmed.) A memory record is small and structured — a fact, a decision, a stated preference, a step-by-step procedure, a gotcha, a reference pointer, or an episodic note — filed at one of six scopes, from user (just you) up through project, workspace, team, company, to client. The scope decides who else's sessions see it once shared infrastructure is connected.

gald3r memory add "Prefer uv over pip" --scope project --type preference \
  -b "This repo uses uv exclusively; never suggest bare pip install." \
  -c 9 --tags tooling,python

gald3r memory list

No memory records found.

(Real output from this checkout — no records exist yet in this worktree; a project with an active memory history returns each record's id/scope/type/title.)

gald3r memory show <record-id>                      # full record detail
gald3r memory supersede <record-id> "New title" ...   # mint a NEW record that supersedes the old one (old kept, chain-linked)
gald3r memory recall "question"                        # chat-native recall over vault notes + memory records together
gald3r memory migrate-learned-facts                     # import .gald3r/learned-facts.md bullets into scoped records (dry-run by default)

Records are never edited in place once superseded — supersede keeps the old record and chains a new one, preserving the history of what changed and when, the same audit-trail principle tasks and bugs follow.

Sharing tiers — `scope`, `share`, `publish`¶

"The scope decides who else's sessions see it once shared infrastructure is connected" (above) — these three verbs are that opt-in mechanism's LOCAL half. Sharing is off by default: a record stays exactly where its --scope puts it until you explicitly authorize it to go further.

gald3r memory scope                # show the sharing-tier model (private-always/team/company/friend/global)
gald3r memory scope <record-id>     # show one record's own scope + local opt-in status
gald3r memory share <record-id> --to team --by "you" --reason "team should know this"
gald3r memory share <record-id> --client-opt-in --by "you" --reason "contract sync"   # for scope=client records
gald3r memory publish --to company  # dry-run preview: what would sync out right now, and why others are refused

None of these three verbs makes a network call — share persists your opt-in decision to a small local ledger (.gald3r/memory/) so it is ready the moment memory sync actually connects; publish previews what the sync gating layer (redaction, scope-promotion authorization, client-scope exclusion) would allow out today, without transmitting anything. Real cross-machine sync (team/company scopes) ships once world_tree is connected — see docs/design/memory-subsystem/P7_sync_wire_shape.md. The global bracket is a separate system entirely: the gald3r-users collective library (not the open internet — see docs/design/collective-brain/), not these scoped memory records.

`gald3r learn` — where the facts come from¶

gald3r learn

Extracts durable facts from recent chat sessions so gald3r doesn't relearn the same thing every session — the harvesting step that feeds memory add/migrate-learned-facts, rather than requiring every fact to be typed in by hand.

The vault: a full knowledge base¶

The vault is a separate, larger surface: plain markdown files (Obsidian-compatible) built from ingested docs, GitHub repos, URLs, and YouTube transcripts — something closer to a personal/team wiki than a short fact list.

A project can point at a shared vault outside any single repo, or fall back to a project-local one at .gald3r/vault when no shared vault is configured — either way, the verb surface is the same:

gald3r vault ingest --title "..." --type <type> --source <url-or-path>   # write a new vault note, routed by type, then reindex
gald3r vault search "keyword"          # ranked keyword search over title/body/tags
gald3r vault list --type <type>        # list notes filtered by type
gald3r vault reindex                    # regenerate the catalog (_index.yaml + index.md)
gald3r vault lint                       # missing frontmatter, empty tags, legacy fields
gald3r vault moc-generate                # generate/update Map-of-Content hub notes per directory

Recon/ingestion pipelines that feed the vault (each with its own dedicated command today, mapped through skills, not yet a single unified CLI ingest surface): a GitHub repo (recon-repo), a docs URL with periodic staleness re-check (recon-docs), a one-time URL snapshot (recon-url), a local file — PDF/DOCX/XLSX/etc. (recon-file), and a YouTube transcript (recon-yt).

Sharing settings — `gald3r vault share`¶

The Collective Brain (docs/design/collective-brain/) turns one user's vault analysis (a GitHub repo, a video, an article) into an instant hit for every other user in the same sharing bracket. Every analysis and every vault note is private by default — nothing leaves this machine until you say otherwise:

gald3r vault share show                                        # current settings (works offline)
gald3r vault share set --default team                          # new analyses default to `team` instead of `private`
gald3r vault share set --add-private-path 'clients/**' --add-private-type client
                                                                 # these never share, no matter what --default says
gald3r vault share check clients/acme/notes.md --to team --type client
                                                                 # dry-run: would this be refused, and why?

Brackets are private | team | company | global (global is the gald3r-users collective library, not the open internet). A friend bracket does not exist yet (T894). A path or note type in private_always is refused by the share path with a NAMED reason (private_always_path / private_always_type) — never silently dropped — regardless of the default bracket. auto_publish stays false; there is no flag to turn it on yet (a later, separately gated release). None of these three verbs makes a network call — settings persist to .gald3r/config/COLLECTIVE_BRAIN_SHARING.md. The actual publish step (sending an opted-in analysis to world_tree) is a separate, not-yet-shipped verb group that reads these settings as its own gate — see docs/design/collective-brain/01_tiers.md.

Skip-if-unchanged — `gald3r vault changetrack`¶

Before spending on a fresh analysis (an LLM call, a repo clone, a transcript fetch), check whether the source actually changed since the last one (docs/design/collective-brain/ 03_change_tracked_reanalysis.md):

gald3r vault changetrack https://github.com/acme/widget          # default-branch request: cheap-probes live HEAD
gald3r vault changetrack https://github.com/acme/widget --sha abc123def   # pin an exact commit instead
gald3r vault changetrack https://youtube.com/watch?v=XXXX --duration-or-hash 754  # video needs this — T1781 rejects it otherwise
gald3r vault changetrack https://example.com/post --refresh       # force re-analysis (always free — D044)

decision is skipped_unchanged (identity confirmed equal — logged to the vault run log), analyze (new/changed/unresolvable identity, or --refresh), or use_stale_accepted (--stale-ok opted into reusing a same-locator cached copy known to differ). A default-branch repo request whose cached SHA differs from the live HEAD is reported explicitly — "library has <old_key> from <analyzed_at>; HEAD is <new_key>" — never silently substituted. Once an analysis actually runs, persist its identity with gald3r vault ingest --identity-kind repo --repo-url ... --commit-sha ... (or the video/article equivalents) so the next changetrack call has something to compare against.

Which one should I use?¶

You want to...	Use
Remember "always use X, never Y" across every future session in this project	`gald3r memory add --scope project`
Record a one-off decision so it's not re-litigated	`gald3r memory add --type decision`
Build a searchable reference library from external docs/repos	`gald3r vault ingest` (or the `recon-*` skills)
Ask a natural-language question against everything you know	`gald3r memory recall`

Where next¶

coordination.md — the workspace/team/company memory scopes in the context of multi-project sync
troubleshooting.md — what gald3r doctor's vault-related checks mean

Memory & Vault¶

Scoped memory records¶

Sharing tiers — scope, share, publish¶

gald3r learn — where the facts come from¶