Skip to content

eidetic-memory: refresh wrappers (eidetic 0.10) + memory-discipline convention #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
OriNachum merged 1 commit into from
Jun 24, 2026
Merged

eidetic-memory: refresh wrappers (eidetic 0.10) + memory-discipline convention #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 35 additions & 13 deletions .claude/skills/recall/scripts/recall.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,11 @@
# forwards every flag verbatim — so `recall.sh "<query>" --mode hybrid --json`
# is exactly `eidetic recall "<query>" --mode hybrid --json`.
#
# The store is the files backend at ~/.eidetic/memory by default — a home-dir
# path OUTSIDE any git worktree, so Claude and the colleague backend (which runs
# in throwaway worktrees) read the SAME memories. Set EIDETIC_DATA_DIR to opt out
# of sharing; set EIDETIC_MONGO_URI / NEO4J_URI + --backend for a server store.
# The store is the files backend. Default location resolves per-operation:
# PUBLIC records inside a git repo → <repo-root>/.eidetic/memory (committed,
# team-shared); PRIVATE records, or any record outside a git repo →
# $HOME/.eidetic/memory (never committed). Recall reads both stores and merges.
# An explicit EIDETIC_DATA_DIR wins and short-circuits to that single dir.

set -euo pipefail

Expand All @@ -34,12 +35,10 @@ resolve_eidetic() {
fi
dir=$(dirname "$dir")
done
cat >&2 <<'EOF'
error: eidetic CLI not found.
hint: install it with `uv tool install eidetic-cli` (or `pipx install eidetic-cli`),
or run from inside the eidetic-cli checkout with `uv` available.
The console script is `eidetic` (dist name: eidetic-cli).
EOF
# In a vendored copy there is no eidetic-cli checkout to fall back to, so the
# only honest remedy is to install the CLI. One `error:` + one `hint:` line.
printf 'error: eidetic CLI not found.\n' >&2
printf 'hint: install it with: uv tool install eidetic-cli (or pipx install eidetic-cli); the console script is eidetic.\n' >&2
return 1
}

Expand All @@ -65,10 +64,17 @@ EOF
}

case "${1:-}" in
-h | --help | help | "")
-h | --help)
usage
exit 0
;;
"")
# A missing query is a usage error, not success. The bareword `help` is
# a legitimate search term, so it is intentionally NOT a usage alias.
printf 'error: no query given.\n' >&2
printf 'hint: recall.sh "<query>" [--mode ...] [--json]; run recall.sh --help for usage.\n' >&2
exit 1
;;
esac

resolve_eidetic || exit 2
Expand Down Expand Up @@ -100,9 +106,12 @@ resolve_scope() {
# inline `# comment` or trailing space can't bleed into the scope),
# then strip surrounding quotes only — matching the canonical parser
# in .claude/skills/cicd/scripts/_resolve-nick.sh.
# `|| true`: under `set -o pipefail`, `head -n1` closing the pipe
# early can SIGPIPE `sed`, making the substitution non-zero and
# aborting the script. An empty parse must yield "" here, not exit.
suffix=$(sed -n \
's/^[[:space:]]*-\{0,1\}[[:space:]]*suffix:[[:space:]]*\([^[:space:]]*\).*/\1/p' \
"$dir/culture.yaml" | head -n1 | tr -d "\"'")
"$dir/culture.yaml" | head -n1 | tr -d "\"'" || true)
break
fi
dir=$(dirname "$dir")
Expand All @@ -127,7 +136,20 @@ if ! has_flag --scope "$@"; then
EIDETIC_SCOPE=$(resolve_scope)
if [ -n "$EIDETIC_SCOPE" ]; then
SCOPE_ARGS+=(--scope "$EIDETIC_SCOPE")
has_flag --visibility "$@" || SCOPE_ARGS+=(--visibility private)
# rollout-cli eidetic-memory recipe POLICY OVERRIDE (not eidetic's
# upstream private default): default to PUBLIC, so a plain recall queries
# the in-repo public pool (<repo>/.eidetic/memory) this repo writes to.
# Pass --visibility private to also surface this agent's private ($HOME)
# notes. The two-store read model reads both dirs regardless.
has_flag --visibility "$@" || SCOPE_ARGS+=(--visibility public)
elif ! has_flag --visibility "$@"; then
Comment on lines +139 to +145

@qodo-code-review qodo-code-review Bot Jun 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

2. recall skill.md out-of-date 📜 Skill insight ✧ Quality

recall.sh now injects --visibility public by default, but .claude/skills/recall/SKILL.md (and
the script’s own explanatory comments) still describe a personal/private default scope and
home-directory store location. This mismatch can create incorrect operational expectations,
confusingly missing results when private memories aren’t surfaced, and inconsistent behavior across
agents.
Agent Prompt 
## Issue description
The `recall` skill’s runtime behavior changed (it now injects `--visibility public` by default), but `.claude/skills/recall/SKILL.md` and `recall.sh`’s own explanatory comment block still describe the old private/personal-default behavior and legacy store expectations (e.g., `~/.eidetic/memory`). Update the documentation and script comments so they accurately reflect the current default visibility and any relevant routing/store semantics, in line with the requirement that SKILL.md must not lag behind implementation.

## Issue Context
- `recall.sh` now injects `--visibility public` by default, including when it resolves a `culture.yaml` suffix.
- The recall skill documentation (SKILL.md) still states the wrapper defaults to a personal/private scope, implies that a no-flag recall returns private records by default, and references a home-directory store location.
- The script’s comment block still describes the older private-default model, which can mislead users/agents into thinking private memories will be returned without explicitly setting visibility.
- The expected fix is to update SKILL.md (frontmatter + body) to match the new defaults and “two-store routing semantics,” update the recall.sh comment block to match the implemented default, and tighten any warning text that still references a private personal-scope default that no longer applies.

## Fix Focus Areas
- .claude/skills/recall/SKILL.md[1-22]
- .claude/skills/recall/SKILL.md[114-129]
- .claude/skills/recall/scripts/recall.sh[82-99]
- .claude/skills/recall/scripts/recall.sh[134-153]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

# No suffix AND no explicit --visibility: the query runs against
# eidetic's own default (scope=default, visibility=public), not this
# agent's private personal scope — so an empty result isn't silently
# misread. Warn on stderr (stdout stays clean for --json). Warn ONLY
# here: an explicit --scope (outer guard) or --visibility (this guard) is
# a deliberate choice, honored verbatim, so either flag silences this.
printf 'warning: no culture.yaml suffix resolved; querying the public default scope rather than a private personal scope. Pass --scope or --visibility to target deliberately.\n' >&2
fi
fi

Expand Down
52 changes: 39 additions & 13 deletions .claude/skills/remember/scripts/remember.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,11 @@
# Upsert is idempotent by id (and dedups by content hash): re-remembering the
# same record updates it in place, never duplicates.
#
# The store is the files backend at ~/.eidetic/memory by default — a home-dir
# path OUTSIDE any git worktree, so a record Claude remembers is recallable by
# the colleague backend (which runs in throwaway worktrees), and vice versa.
# Set EIDETIC_DATA_DIR to opt out of sharing; use --backend mongo|neo4j (with
# The store is the files backend. Default location resolves per-operation:
# PUBLIC records inside a git repo → <repo-root>/.eidetic/memory (committed,
# team-shared); PRIVATE records, or any record outside a git repo →
# $HOME/.eidetic/memory (never committed). An explicit EIDETIC_DATA_DIR still
# wins and short-circuits to that single dir. Use --backend mongo|neo4j (with
# EIDETIC_MONGO_URI / NEO4J_URI) for a server-backed shared store.

set -euo pipefail
Expand All @@ -40,12 +41,10 @@ resolve_eidetic() {
fi
dir=$(dirname "$dir")
done
cat >&2 <<'EOF'
error: eidetic CLI not found.
hint: install it with `uv tool install eidetic-cli` (or `pipx install eidetic-cli`),
or run from inside the eidetic-cli checkout with `uv` available.
The console script is `eidetic` (dist name: eidetic-cli).
EOF
# In a vendored copy there is no eidetic-cli checkout to fall back to, so the
# only honest remedy is to install the CLI. One `error:` + one `hint:` line.
printf 'error: eidetic CLI not found.\n' >&2
printf 'hint: install it with: uv tool install eidetic-cli (or pipx install eidetic-cli); the console script is eidetic.\n' >&2
return 1
}

Expand All @@ -60,7 +59,9 @@ Usage:

A record needs `id`, `text`, and `type`; `hash` and `metadata` are recommended
(hash is derived from text when omitted). Upsert is idempotent by id.
Public data only. Every flag is forwarded verbatim to `eidetic remember`.
Records default to this agent's PRIVATE personal scope (--scope from the
culture.yaml suffix); pass --visibility public to contribute to the shared
public pool. Every flag is forwarded verbatim to `eidetic remember`.
See `eidetic explain remember`.
EOF
}
Expand All @@ -72,6 +73,16 @@ case "${1:-}" in
;;
esac

# No record argument AND stdin is an interactive terminal → `eidetic remember`
# would block forever waiting for NDJSON. Show usage instead of hanging. A piped
# or redirected stdin (`cat records.ndjson | remember.sh`) is not a TTY and
# proceeds to the batch path normally.
if [ "$#" -eq 0 ] && [ -t 0 ]; then
usage >&2
printf 'hint: pass a JSON record as an argument, or pipe NDJSON on stdin.\n' >&2
exit 1
fi

resolve_eidetic || exit 2

# ── default to this agent's PERSONAL, PRIVATE scope (culture.yaml `suffix`) ──
Expand Down Expand Up @@ -100,9 +111,12 @@ resolve_scope() {
# inline `# comment` or trailing space can't bleed into the scope),
# then strip surrounding quotes only — matching the canonical parser
# in .claude/skills/cicd/scripts/_resolve-nick.sh.
# `|| true`: under `set -o pipefail`, `head -n1` closing the pipe
# early can SIGPIPE `sed`, making the substitution non-zero and
# aborting the script. An empty parse must yield "" here, not exit.
suffix=$(sed -n \
's/^[[:space:]]*-\{0,1\}[[:space:]]*suffix:[[:space:]]*\([^[:space:]]*\).*/\1/p' \
"$dir/culture.yaml" | head -n1 | tr -d "\"'")
"$dir/culture.yaml" | head -n1 | tr -d "\"'" || true)
break
fi
dir=$(dirname "$dir")
Expand All @@ -127,7 +141,19 @@ if ! has_flag --scope "$@"; then
EIDETIC_SCOPE=$(resolve_scope)
if [ -n "$EIDETIC_SCOPE" ]; then
SCOPE_ARGS+=(--scope "$EIDETIC_SCOPE")
has_flag --visibility "$@" || SCOPE_ARGS+=(--visibility private)
# rollout-cli eidetic-memory recipe POLICY OVERRIDE (not eidetic's
# upstream private default): default to PUBLIC so a plain remember lands
# in <repo>/.eidetic/memory — committed, team- and mesh-shared. Pass
# --visibility private to keep a record in $HOME (uncommitted).
has_flag --visibility "$@" || SCOPE_ARGS+=(--visibility public)
elif ! has_flag --visibility "$@"; then
Comment on lines +144 to +149

@qodo-code-review qodo-code-review Bot Jun 24, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. remember skill.md out-of-date 📜 Skill insight ✧ Quality

remember.sh now injects --visibility public by default, but both its usage() output and
.claude/skills/remember/SKILL.md still document an old private/personal default (including the
~/.eidetic/memory home-dir location) and even advise passing --visibility public. This mismatch
can mislead users/agents into relying on incorrect behavior and unintentionally writing records to
the shared public/committed store when they expected private notes.
Agent Prompt 
## Issue description
The `remember` skill’s actual default visibility/store behavior has changed (the wrapper now injects `--visibility public` by default), but `.claude/skills/remember/SKILL.md` and the wrapper’s `usage()` output still describe the old behavior (private/personal by default, home-directory store, and suggesting `--visibility public` as opt-in). Update the documentation and help text so they no longer lag the implementation and so users/agents can intentionally choose public vs private storage.

## Issue Context
- `remember.sh` now injects `--visibility public` by default (policy override), especially when it resolves a `culture.yaml` suffix.
- The script’s `usage()` output and `.claude/skills/remember/SKILL.md` still claim the default is private/personal, reference `~/.eidetic/memory`, and advise passing `--visibility public`—which is now reversed.
- CLAUDE.md documents the intended new default as public.
- Expected behavior to document: default is **public** (in-repo when applicable); `--visibility private` should route to `$HOME`/personal storage.

## Fix Focus Areas
- .claude/skills/remember/SKILL.md[1-20]
- .claude/skills/remember/SKILL.md[61-100]
- .claude/skills/remember/scripts/remember.sh[51-67]
- .claude/skills/remember/scripts/remember.sh[88-104]
- .claude/skills/remember/scripts/remember.sh[139-158]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

# No suffix AND no explicit --visibility: the record falls back to
# eidetic's own default (scope=default, visibility=public). Don't let an
# expected-private record go public silently — warn on stderr (stdout
# stays clean for --json). Warn ONLY here: an explicit --scope (outer
# guard) or --visibility (this guard) means the caller chose deliberately
# and is honored verbatim, so either flag silences this.
printf 'warning: no culture.yaml suffix resolved; this record falls back to the public default scope. Pass --scope or --visibility to place it deliberately.\n' >&2
fi
fi

Expand Down
39 changes: 39 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,45 @@ All notable changes to this project will be documented in this file.
Format follows [Keep a Changelog](https://keepachangelog.com/). This project
adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.8.0] - 2026-06-24

### Added

- **Memory-discipline "Conventions and workflow" section in `CLAUDE.md`** — a
per-task *recall-before / remember-after* convention (scope localized to this
repo's nick) so the vendored `remember` / `recall` skills are actually used,
not just present: `/recall` before non-trivial work to build on prior
decisions instead of re-deriving them, and `/remember` when a non-obvious
decision, constraint, fix-and-why, or hard-won gotcha surfaces. The section
documents this repo's memory as **in-repo and public** — records resolve to
`<repo-root>/.eidetic/memory` (committed, team- and mesh-shared). Inserted
idempotently (skipped if already present), slotted under an existing
"Conventions and workflow" heading when one exists, else appended.

### Changed

- **Refreshed the `remember` + `recall` wrappers from eidetic-cli 0.10.0**
(cite-don't-import) — picks up eidetic's **project-local store default**: the
files backend now resolves per record by visibility — PUBLIC records inside a
git repo go to `<repo-root>/.eidetic/memory` (committed, team-shared), PRIVATE
records (or any record outside a repo) go to `$HOME/.eidetic/memory` (never
committed), an explicit `EIDETIC_DATA_DIR` still wins, and recall reads both
stores and merges. Also carries the 0.9.3 hardening (interactive-stdin guard,
`help` as a search term, SIGPIPE-safe suffix parsing). **Recipe policy
override (the wrappers here are NOT byte-verbatim):** the injected default
visibility is flipped from eidetic's `private` to **`public`**, so a plain
`/remember` lands the note in `./.eidetic/memory` in this repo, kept as part
of the repo — pass `--visibility private` to route a record to `$HOME`
instead. `remember` drives `eidetic remember` (idempotent upsert of one JSON
record or an NDJSON batch on stdin); `recall` drives `eidetic recall` with
four search modes (exact / approximate / keyword / hybrid). Each `SKILL.md` is
localized only in the illustrative `--scope <nick>` examples (Provenance keeps
"First-party to eidetic-cli"). Runtime dep: the `eidetic` CLI on PATH (else a
local eidetic-cli checkout with `uv`) — **`eidetic >= 0.10.0`** for the
in-repo routing; on an older CLI the public records still work but are stored
in `$HOME/.eidetic/memory` instead of in-repo. Propagated by rollout-cli's
`eidetic-memory` recipe.

## [0.7.0] - 2026-06-23

### Added
Expand Down
28 changes: 28 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -292,3 +292,31 @@ git grep -nw data-refinery-cli # dist/nick name
git grep -nw data_refinery # python package
git grep -nw data-refinery # CLI command
```

## Conventions and workflow

**Memory discipline — recall before, remember after.** This repo keeps its
eidetic memory **in-repo and public**: records resolve to
`<repo-root>/.eidetic/memory` — committed, and shared with the team and mesh
peers (the `claude` and `colleague` backends both read the same
`data-refinery-cli` scope), so memory travels with the repo, not a private
home-dir store. Make it a per-task habit:

- **`/recall` before you start.** Search the store for the area you're about
to touch — prior decisions, gotchas, "have we done this before?" — so you
build on what's already known instead of re-deriving it. Do this before
non-trivial tasks, not just when asked.
- **`/remember` when something worth keeping surfaces.** A non-obvious
decision and its rationale, a constraint, a fix and *why* it was needed, a
gotcha that cost time, a fact the next session would otherwise re-learn.
Capture it as it happens, not at the end when it's faded.

A plain `/remember` lands the note in `./.eidetic/memory` in this repo — no
flag needed (the wrappers here default to `--visibility public`; in-repo
routing needs `eidetic >= 0.10.0`, older CLIs keep records in `$HOME`). Keep
something out of the committed store only by passing `--visibility private`
(routes to `$HOME/.eidetic/memory`, never committed); `/recall` reads both
stores and merges. Don't store what the repo already records (code structure,
git history, what's already in this file or `CHANGELOG.md`) — store what you'd
have to re-derive. These are the `recall`/`remember` skills (`.claude/skills/`),
backed by the `eidetic` store.
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "data-refinery-cli"
version = "0.7.0"
version = "0.8.0"
description = "Agent and CLI for data quality in storage and retrieval — validating, deduplicating, and checking the integrity and freshness of data as it is stored and fetched. Split out of eidetic-cli so eidetic keeps agent-memory; sibling to daria, the Data Refinery Intelligent Agent."
readme = "README.md"
license = "Apache-2.0"
Expand Down
Loading