Skip to content

Add eidetic remember/recall memory skills #2

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 23, 2026
Merged

Add eidetic remember/recall memory skills #2

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
181 changes: 181 additions & 0 deletions .claude/skills/recall/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
---
name: recall
type: command
description: >
Search the shared eidetic memory store and get back ranked, provenanced
records. Drives `eidetic recall` with four search modes — exact (verbatim
substring), approximate (vector/semantic), keyword (BM25 lexical), and hybrid
(a weighted blend of vector+keyword, the default) — each hit carrying its
text, full metadata, a relevance `score`, and a freshness `signal`. Recall
passively reinforces matched records (bumps last_recall + recall_count).
Shadowed and archived records are excluded by default; use
--include-shadowed / --include-archived to retrieve them. The store lives at
~/.eidetic/memory (a home-dir path outside any git worktree); the wrapper
defaults queries to this agent's PERSONAL, PRIVATE scope (`--scope reduce-cli
--visibility private`, suffix read from culture.yaml) — matching where
/remember writes — so a no-flag recall returns this agent's own private records
plus the shared public pool, and Claude and the colleague backend recall each
other's memories because both resolve the same suffix via this skill. Use
when the user says "recall", "what do we know about X", "search memory",
"have we seen X before", "look it up in memory", "eidetic recall", or before
answering from scratch when prior context may already be stored. Pairs with
the sibling /remember skill.
---

# recall — search the shared eidetic memory

`recall` drives **`eidetic recall`**: given a query, it returns the top-k stored
records ranked by relevance, each with its `text`, full `metadata` (provenance),
a numeric `score`, and a freshness `signal`. It is the read half of the memory
surface; the write half is the sibling **/remember** skill.

The point of a *shared* store is that memory is a **team faculty**, not a
per-agent silo: a record Claude wrote is recallable by the colleague backend
(and vice versa), because both resolve the same `~/.eidetic/memory` path.

## How to run

```bash
bash .claude/skills/recall/scripts/recall.sh "<query>" [flags...]
```

The wrapper resolves the CLI portably (installed `eidetic` on `PATH`, else
`uv run eidetic` from the checkout) and forwards every flag verbatim, so it is
exactly `eidetic recall …`. Run it from anywhere; the store is the same.

## Search modes (`--mode`, default `hybrid`)

| Mode | What it matches | Needs embed server? |
|------|-----------------|---------------------|
| `exact` | case-insensitive verbatim substring (`--case-sensitive` to tighten) | no — offline-safe |
| `approximate` | vector cosine / semantic similarity | yes (falls back offline) |
| `keyword` | BM25 lexical; only records sharing a query term | no — offline-safe |
| `hybrid` | `alpha*approximate + (1-alpha)*keyword` (`--alpha`, default 0.5) | uses it when up |

`hybrid` is the default because the two signals cover each other's blind spots:
vector catches paraphrases, keyword catches exact ids/quotes. When the embed
server is unreachable, `hybrid` collapses to keyword-only (it never fuses
meaningless offline-fallback cosine).

## Output fields

Each hit in `--json` output includes:

| Field | Notes |
|-------|-------|
| `id` | stable record identity |
| `text` | the stored chunk |
| `type` | record type |
| `metadata` | full provenance, round-tripped verbatim from ingest |
| `score` | relevance score from the chosen search mode (freshness-blended) |
| `signal` | freshness strength in [0, 1]; computed at recall time from age, recall frequency, and staleness |
| `created` | ISO-8601 ingest date (may be DATE_UNKNOWN for legacy records) |
| `last_recall` | ISO-8601 timestamp of the most recent recall hit (null if never recalled) |
| `recall_count` | number of times this record has been recalled (passive reinforcement counter) |
| `lifecycle` | `active`, `shadowed`, or `archived` |
| `links` | list of related-memory ids |

## Freshness signal

Every `recall` hit carries a `signal` field (float in `[0, 1]`). The signal
blends **multiplicatively** into the lexical/vector score so recently-created
and frequently-recalled records surface ahead of stale ones. The formula:

```
access_bonus = min(0.5, recall_count * 0.05)
age_factor = 1 / (1 + days_since_creation * 0.01)
staleness = days_since_last_recall * 0.01
signal = clamp((0.5 - staleness + access_bonus) * age_factor, 0, 1)
blended_score = score * (1 + 0.25 * (signal - 0.5))
```

Records with no temporal data (legacy, undated) are an exact no-op — the blend
is skipped for them so pre-existing fixture scores are unchanged.

Each `recall` call is also **passive reinforcement**: it bumps `last_recall` and
`recall_count` on every matched record, so frequently-recalled memories organically
gain signal strength over time.

## Lifecycle flags

By default, `recall` returns only `active` records. Use these flags to retrieve
non-active records:

- `--include-shadowed` — include records whose `lifecycle == "shadowed"` (records
superseded within their scope by a newer record). Shadowed records are preserved
and still searchable; they are just hidden from the default result set.
- `--include-archived` — include records whose `lifecycle == "archived"` (records
older than ~1 year or below the signal threshold). Archived records are fully
preserved; the flag makes them retrievable again.

Both flags can be combined. Neither affects ranking — shadowed/archived records
compete on score/signal just like active ones when included.

## Common flags (forwarded to `eidetic recall`)

- `--mode exact|approximate|keyword|hybrid` — default `hybrid`.
- `--top-k N` — max results (default 5).
- `--alpha F` — hybrid blend weight in `[0,1]` (default 0.5).
- `--case-sensitive` — for `--mode exact`.
- `--filter KEY=VALUE` — metadata facet filter (repeatable): e.g. `--filter source=docs`.
- `--scope NAME` / `--visibility public|private` — scope isolation (no private
leak). **The wrapper defaults this to the agent's PERSONAL, PRIVATE scope**
(`--scope reduce-cli --visibility private`, suffix read from `culture.yaml`),
matching where `/remember` writes — so a no-flag recall returns this agent's
own private records **plus** the shared public pool, while those private records
stay invisible to a `default`/other-scope recall. Pass `--scope`/`--visibility`
to query elsewhere; a wheel install with no `culture.yaml` falls back to the
CLI default `default`/`public`.
- `--backend files|mongo|neo4j` — default `files` (the shared home-dir store).
- `--include-shadowed` — include shadowed records in results (excluded by default).
- `--include-archived` — include archived records in results (excluded by default).
- `--json` — structured list to stdout (use this when an agent parses the result).

## Examples

```bash
# Default hybrid recall, JSON for an agent to parse:
bash .claude/skills/recall/scripts/recall.sh "jetson nano power draw" --json

# Find the exact message that mentions a phrase:
bash .claude/skills/recall/scripts/recall.sh "Orin Nano" --mode exact

# Keyword search, offline-safe, narrowed to a source:
bash .claude/skills/recall/scripts/recall.sh "thermal throttle" --mode keyword \
--filter source=discord --top-k 10

# Retrieve a record that was recently shadowed (its superseding record is now active):
bash .claude/skills/recall/scripts/recall.sh "old topic" --include-shadowed --json

# Retrieve all records including archived (to audit stale memories):
bash .claude/skills/recall/scripts/recall.sh "power" --include-archived --include-shadowed --json
```

## Notes

- **Provenance is mandatory** on every hit — recall is for *cited* answers.
- The embed endpoint defaults to the local model-gear embed gear
(`http://localhost:8002/v1`, model `Qwen/Qwen3-Embedding-0.6B`); override with
`EIDETIC_EMBED_URL` / `EIDETIC_EMBED_MODEL`. `exact`/`keyword` ignore it.
- **Use the wrapper, not a bare `eidetic`.** The console script may not be on
`PATH` (in a dev checkout it isn't) — the wrapper resolves it for you (`PATH`
first, else `uv run eidetic`). For the docs, run `eidetic explain recall` if
installed, otherwise `uv run --project <eidetic-cli checkout> eidetic explain
recall`. (`explain` is an **`eidetic`** verb — a sibling tool like `devex`
won't know it.)
- **Reading scores:** `exact`, `keyword`, and `hybrid` drop non-matching records
(hybrid drops any record with a `0.0` blended score), so their hits are real
matches. `approximate` keeps every candidate ranked by raw cosine, so it can
return low/near-zero scores when the store is small — lower `--top-k` to trim.
A `--min-score` threshold is a tracked follow-up.
- **Sharing scope = one OS user.** The default store is `~/.eidetic/memory`, so
every agent/process running as the *same* OS user shares it (that is the point —
Claude + colleague). It is not isolated between OS users by anything but file
permissions; keep genuinely private data in a `--visibility private` scope and
treat the host as the trust boundary.

## Provenance

First-party to **eidetic-cli** — eidetic owns its memory surface. Cite, don't
import: downstream repos copy this skill, they don't symlink it. See
[`docs/skill-sources.md`](../../../docs/skill-sources.md).
141 changes: 141 additions & 0 deletions .claude/skills/recall/scripts/recall.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
#!/usr/bin/env bash
# recall.sh — search the shared eidetic memory store (the /recall skill).
#
# Thin, portable wrapper around `eidetic recall`. It resolves the CLI, points
# the embedding modes at the local model-gear embed gear (overridable), and
# 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.

set -euo pipefail

# ── resolve the eidetic CLI (installed tool first, then dev checkout) ────────
EIDETIC=()
resolve_eidetic() {
if command -v eidetic >/dev/null 2>&1; then
EIDETIC=(eidetic) # installed console script — the normal case
return 0
fi
# Dev fallback: inside the eidetic-cli checkout, run via uv.
local dir
dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
while [ -n "$dir" ] && [ "$dir" != "/" ]; do
if [ -f "$dir/pyproject.toml" ] \
&& grep -q '^name = "eidetic-cli"' "$dir/pyproject.toml" 2>/dev/null; then
if command -v uv >/dev/null 2>&1; then
EIDETIC=(uv run --project "$dir" eidetic)
return 0
fi
break
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
return 1
Comment on lines +16 to +43

@qodo-code-review qodo-code-review Bot Jun 23, 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. Broken uv fallback lookup 🐞 Bug ☼ Reliability

recall.sh/remember.sh claim a dev-checkout fallback, but resolve_eidetic() only searches for
an eidetic-cli pyproject.toml in ancestor directories of the wrapper script path, so it cannot
find a separate local eidetic-cli checkout when these skills are vendored into this repo. If
eidetic is not on PATH, both skills will always exit with an error even when uv + a local
eidetic-cli checkout are available.
Agent Prompt 
### Issue description
The wrappers’ dev fallback cannot succeed in this repository because it walks up from the wrapper’s own directory and looks for `pyproject.toml` named `eidetic-cli`. Since these scripts live under `reduce-cli`, they will never be inside an `eidetic-cli` checkout, so the fallback is effectively dead code.

### Issue Context
- Current logic uses `dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)` and walks upward.
- In this repo, the only root `pyproject.toml` is `name = "reduce-cli"`, so the grep for `eidetic-cli` never matches.

### Fix Focus Areas
- .claude/skills/recall/scripts/recall.sh[16-43]
- .claude/skills/remember/scripts/remember.sh[23-50]

### Suggested fix approach
- Change the fallback search root to something that can actually be inside an `eidetic-cli` checkout (e.g., walk up from `$PWD`, or from `git rev-parse --show-toplevel`, similar to how `ask-colleague` does it).
- Optionally add an explicit override like `EIDETIC_PROJECT=/path/to/eidetic-cli` (or `EIDETIC_BIN`) that, when set, is used directly.
- Update the error hint text to match the new behavior (so it’s not instructing users to do something that can’t work).

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

}

usage() {
cat <<'EOF'
recall.sh — search the shared eidetic memory store (the /recall skill).

Usage:
recall.sh "<query>" [--mode exact|approximate|keyword|hybrid] [--top-k N] \
[--alpha F] [--case-sensitive] [--filter KEY=VALUE]... \
[--backend files|mongo|neo4j] [--scope NAME] [--visibility public|private] \
[--json]

Modes (default: hybrid):
exact case-insensitive verbatim substring (--case-sensitive to tighten); offline-safe
approximate vector cosine / semantic similarity (uses the embed server)
keyword BM25 lexical; only records sharing a query term; offline-safe
hybrid alpha*approximate + (1-alpha)*keyword (--alpha, default 0.5);
degrades to keyword-only when the embed server is offline

Every flag is forwarded verbatim to `eidetic recall`. See `eidetic explain recall`.
EOF
}

case "${1:-}" in
-h | --help | help | "")
usage
exit 0
;;
esac

resolve_eidetic || exit 2

# ── default to this agent's PERSONAL, PRIVATE scope (culture.yaml `suffix`) ──
# Query this agent's OWN personal scope by default, matching where /remember
# writes, instead of the global `default` scope shared by every project on this
# host. We read the `suffix` from the nearest culture.yaml (walking up from this
# script), so the scope follows the repo identity rather than being hard-coded —
# a downstream cite-don't-import copy adapts to its own suffix, and the colleague
# backend (running in a worktree of this same repo) resolves the same suffix,
# keeping the Claude↔colleague shared-memory story intact.
#
# The personal scope is PRIVATE by default to match /remember: in eidetic's model
# a private record is served only to a recall in the SAME scope (`can_serve`), so
# querying with --scope <suffix> --visibility private is what retrieves those
# isolated records (a public/default recall can't see them). Scope and visibility
# are paired — the private default applies only when we inject the resolved scope,
# and only if the caller didn't pass --visibility (so an explicit
# `--visibility public` still wins). An explicit --scope on the command line takes
# over steering entirely; a wheel install with no culture.yaml falls back to the
# plain CLI default (`default`/`public`).
resolve_scope() {
local dir suffix=""
dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
while [ -n "$dir" ] && [ "$dir" != "/" ]; do
if [ -f "$dir/culture.yaml" ]; then
# Capture only the first non-space token after `suffix:` (so an
# 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.
suffix=$(sed -n \
's/^[[:space:]]*-\{0,1\}[[:space:]]*suffix:[[:space:]]*\([^[:space:]]*\).*/\1/p' \
"$dir/culture.yaml" | head -n1 | tr -d "\"'")
break
fi
dir=$(dirname "$dir")
done
printf '%s' "$suffix"
}

has_flag() {
local needle=$1
shift
local a
for a in "$@"; do
case "$a" in
"$needle" | "$needle"=*) return 0 ;;
esac
done
return 1
}

SCOPE_ARGS=()
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)
fi
fi

# Default the embedding endpoint to the local model-gear embed gear. eidetic
# falls back to a deterministic offline embedding if it's unreachable, so this
# is safe even when the gear is down. Override by exporting these yourself.
: "${EIDETIC_EMBED_URL:=http://localhost:8002/v1}"
: "${EIDETIC_EMBED_MODEL:=Qwen/Qwen3-Embedding-0.6B}"
export EIDETIC_EMBED_URL EIDETIC_EMBED_MODEL

exec "${EIDETIC[@]}" recall "${SCOPE_ARGS[@]}" "$@"
Loading
Loading