Skip to main content
rule CX Codex

dynamic-recall — Claude Code rule: what it does, how to install

dynamic-recall directs Claude Code to query and store session learnings, architectural decisions, and error fixes using hybrid semantic search.

MIT ★ 3,951 updated 2026-01-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/dynamic-recall.md
Open on GitHub

What dynamic-recall does

The rule guides the agent to query a persistent semantic memory system before tackling difficult tasks, debugging, or designing architecture. It relies on uv run python scripts/core/recall_learnings.py to retrieve past context. By default, queries run as a hybrid RRF search combining text matches with 1024-dimensional BGE embeddings.

PostgreSQL acts as the primary backend via DATABASE_URL. The local SQLite file at ~/.claude/cache/memory.db serves only as a fallback. Without the $CLAUDE_OPC_DIR environment variable pointing to the correct directory, the script fails to load required settings.

Learnings are written via store_learning.py with typed classifications such as ARCHITECTURAL_DECISION or FAILED_APPROACH. This setup prevents repeating mistakes across coding sessions.

What it helps with

  • recall previous error resolutions before debugging
  • persist architectural choices across distinct sessions
  • search past codebase patterns using hybrid vector search
  • record failed approaches to avoid repeating errors

Example prompts for the agent

  • Check semantic memory for how we resolved pytest test failures previously
  • Recall architectural decisions regarding the YAML handoff format
  • Save this working hook build step into memory with WORKING_SOLUTION type

How to install dynamic-recall

Manually: put the files in place

.claude/rules/dynamic-recall.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about dynamic-recall

How do I install dynamic-recall in Claude Code?

Place the rule file at .claude/rules/dynamic-recall.md inside your repository. Claude Code reads this file automatically during session startup.

What does the dynamic-recall rule do?

It instructs the agent to query semantic memory through recall_learnings.py and record discoveries with store_learning.py. This ensures architectural decisions and bug fixes carry over into future sessions.

Which database backend does dynamic-recall use?

It defaults to PostgreSQL through the DATABASE_URL connection string. The fallback SQLite database at ~/.claude/cache/memory.db may be unpopulated, so do not rely on it as primary storage.

Source text

dynamic-recall.md · MIT
# Dynamic Recall

You have access to a semantic memory system that stores learnings, decisions, and patterns from past sessions.

## When to Use Recall

Query memory proactively when:
- Starting work on something you may have done before
- Encountering an error or tricky situation
- Making architectural or design decisions
- Looking for patterns or approaches that worked previously

## How to Recall

```bash
(cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/recall_learnings.py --query "your search terms")
```

**IMPORTANT:** Always run from `opc/` directory to load correct environment variables.

### Options

```bash
# Default: Hybrid RRF search (text + vector combined) - RECOMMENDED
(cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/recall_learnings.py --query "authentication patterns")

# More results
(cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/recall_learnings.py --query "error handling" --k 10)

# Pure vector search (higher similarity scores, 0.4-0.6 range)
(cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/recall_learnings.py --query "database schema" --vector-only)

# Text-only search (fast, no embeddings)
(cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/recall_learnings.py --query "YAML format" --text-only)
```

## Backend Architecture

| Backend | Location | Status |
|---------|----------|--------|
| **PostgreSQL** (primary) | Via DATABASE_URL | Has 100+ real learnings with BGE embeddings |
| SQLite (fallback) | ~/.claude/cache/memory.db | May be empty - don't rely on it |

**DO NOT manually inspect databases** - just use the recall script. It auto-selects the correct backend.

## Understanding Scores

| Search Mode | Score Range | Interpretation |
|-------------|-------------|----------------|
| Hybrid RRF (default) | 0.01-0.03 | Normal - RRF combines rankings |
| Pure vector | 0.4-0.6 | Cosine similarity |
| Text search | 0.01-0.05 | BM25 normalized |

Low RRF scores (0.02) are **good results** - don't confuse with low relevance.

## What's Stored

The memory contains session learnings from `archival_memory` table:
- **What worked**: Successful approaches and solutions
- **What failed**: Pitfalls to avoid
- **Decisions**: Architectural choices and rationale
- **Patterns**: Reusable approaches

All entries have 1024-dim BGE embeddings (bge-large-en-v1.5) for semantic search.

## Example Queries

- "hook development patterns" - find past hook implementations
- "TypeScript type errors" - recall how similar errors were fixed
- "database migration" - find migration patterns used before
- "test failures pytest" - recall debugging approaches
- "YAML handoff format" - recall format decisions

Use recall to avoid repeating mistakes and leverage past successes.

## How to Store Learnings

When you discover something worth remembering, store it:

```bash
cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/store_learning.py \
  --session-id "<short-identifier>" \
  --type <TYPE> \
  --content "<what you learned>" \
  --context "<what it relates to>" \
  --tags "tag1,tag2,tag3" \
  --confidence high|medium|low
```

**IMPORTANT:** Use `cd <absolute-path>` not `(cd opc && ...)` - the subshell form can cause path doubling errors.

### Learning Types

| Type | Use For |
|------|---------|
| `ARCHITECTURAL_DECISION` | Design choices, system structure decisions |
| `WORKING_SOLUTION` | Fixes, solutions that worked |
| `CODEBASE_PATTERN` | Patterns discovered in code |
| `FAILED_APPROACH` | What didn't work (avoid repeating) |
| `ERROR_FIX` | How specific errors were resolved |
| `USER_PREFERENCE` | User's preferred approaches |
| `OPEN_THREAD` | Incomplete work to resume later |

### Example

```bash
cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/store_learning.py \
  --session-id "hook-debugging" \
  --type WORKING_SOLUTION \
  --content "TypeScript hooks require npm install in .claude/hooks/ before they work. The build.sh script compiles TS to JS in dist/." \
  --context "hook development and building" \
  --tags "hooks,typescript,build" \
  --confidence high
```

### When to Store

Store learnings when you:
- Solve a tricky problem (so you don't re-solve it)
- Make an architectural decision (capture the rationale)
- Discover a codebase pattern (document it)
- Find something that doesn't work (warn future sessions)

© parcadei · MIT · parcadei/Continuous-Claude-v3

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set161

The whole set →
boundary-value-problems A Claude skill that walks from a boundary value problem statement to a numerical answer: shooting, finite differences, solve_bvp and Sturm–Liouville eigenvalues. CX Codex +1 ★ 3,951repo stars atlas atlas executes acceptance and end-to-end test scenarios across web applications. It inspects your project framework, runs user journeys, and outputs failure artifacts. CX Codex ★ 3,951repo stars judge judge is a Claude Code subagent that reviews refactoring and code transformations, checking behavior changes, code quality, and safety risks. CX Codex ★ 3,951repo stars profiler profiler identifies bottlenecks in your code: slow functions, memory leaks, concurrency bugs. Profiles Python and Node.js, spots N+1 queries and blocking operations. CX Codex ★ 3,951repo stars tldr-cli tldr-cli is a Claude Code rule that directs the agent to use a CLI for exploring code structure and dependencies. It applies during debugging, function searches, and change-impact checks. CX Codex +1 ★ 3,951repo stars scout scout — a subagent for systematic codebase research. Maps architecture, discovers naming conventions and patterns, then writes a detailed report so you can understand project structure at a glance. CX Codex ★ 3,951repo stars herald Herald handles project releases by analyzing commit history, bumping version numbers in configuration files, and drafting changelogs. CX Codex ★ 3,951repo stars surveyor surveyor reviews migrations and upgrades for leftover old APIs, mixed states, dependency drift, and rollback gaps. Use it after changing a framework, library, or infrastructure. CX Codex ★ 3,951repo stars

Project sponsors

Companies that keep this analytics open