Skip to content
Skills Library
AI & agents · Learning & explanation

rekal-usage

/rekal-usage

Operational guide for rekal memory tools. Precise rules for when/how to call each tool, with exact parameters and decision trees. Use at session start, when onboarding to a rekal workspace, or when user asks "how do I use rekal", "what rekal tools", "help with memory". Trigger: /rekal-usage.

Repository
rekal ↗
Licence
MIT
Last repository change
26.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Operational guide for rekal memory tools. Precise rules for when/how to call each tool, with exact parameters and decision trees. Use at session start, when onboarding to a rekal workspace, or when user asks "how do I use rekal", "what rekal tools", "help with memory". Trigger: /rekal-usage.

Triggers from the description

how do I use rekalwhat rekal toolshelp with memory
Original author description

Operational guide for rekal memory tools. Precise rules for when/how to call each tool, with exact parameters and decision trees. Use at session start, when onboarding to a rekal workspace, or when user asks "how do I use rekal", "what rekal tools", "help with memory". Trigger: /rekal-usage.

How it works

  1. The surface
  2. Session start
  3. Recalling
  4. Storing
  5. Do NOT store
  6. Do NOT use rekal for
Original SKILL.md headings · 114 lines, 599 words
SKILL.md preview
---
name: rekal-usage
description: >
  Operational guide for rekal memory tools. Precise rules for when/how to call
  each tool, with exact parameters and decision trees. Use at session start,
  when onboarding to a rekal workspace, or when user asks "how do I use rekal",
  "what rekal tools", "help with memory". Trigger: /rekal-usage.
allowed-tools: mcp__rekal__memory_build_context mcp__rekal__memory_store mcp__rekal__memory_delete
---

You have persistent memory via three rekal MCP tools. Follow these rules exactly.

## The surface

| tool | purpose |
|------|---------|
| `memory_build_context(query, project?, limit?, min_score?)` | recall: hybrid search over stored memories |
| `memory_store(content, project?, tags?, replaces?)` | persist one distilled fact; `replaces=<old_id>` updates an existing one |
| `memory_delete(memory_id)` | remove a memory that is wrong or obsolete |

Admin operations (health report, export, bulk prune) live in the CLI:
`rekal health`, `rekal export`, `rekal prune`.

## Session start

Call `memory_build_context(query="<task description>")` before exploring the
codebase. Read the result before proceeding. Do this EVERY session.

## Recalling

Queries go through hybrid search: BM25 keywords + vector similarity + recency
decay. Results below `min_score` (default 0.25) are dropped, so an empty
result means "nothing relevant", not "nothing stored".

**Do:** Use natural language with domain terms.
```
"JWT refresh token rotation policy": specific, has domain terms
"how to deploy auth service to staging": natural language, synonyms work
"user's preferred formatter and why": retrieves preferences with reasoning
```

**Do not:** Use vague, generic, or garbage queries.
```
"stuff": matches nothing useful
"code": matches everything
"the thing": no semantic content
```

- `project="backend"`: scope to one project. Use in multi-project workspaces.
- Different angle on the same task = new `memory_build_context` call with a
  reworded query.

## Storing

### Rule: ALWAYS recall before storing

```
1. memory_build_context(query="<what you want to store>")
2. Read results:
   ├── Exact duplicate found     → do nothing
   ├── Same topic, outdated info → memory_store(content="...", replaces="<old_id>")
   └── No match                  → memory_store(content="...", tags=[...])
```

Never skip step 1. Duplicates degrade search quality. Two memories about the
same topic must never coexist: `replaces` supersedes the old memory so it
stops surfacing in recall.

### memory_store: exact parameters

```python
memory_store(
    content="Ruff > Black. Faster + handles import sort.",
    tags=["formatting", "ruff"],  # 2-4 specific tags. Not "code" or "project".
    project="backend",  # Set if project-specific. Omit for global knowledge.
    replaces="mem_abc123",  # ID from recall results when updating a topic.
)
```

### Content rules: distill + compress, always

**Never store raw dialogue, conversation turns, or verbose text.**

Distill to the durable fact, then apply caveman-style compression:

**Drop:** articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries, hedging (might/could/maybe). Replace "in order to" → "to". Remove "you should", "make sure to", "remember to". State actions directly. Merge redundant points.

**Keep exact:** technical terms, proper nouns, version numbers, values, reasons, causality (`X → Y`).

```
BAD:  "User said yeah I think maybe we could try using Python for this"
GOOD: "Prefer Python for project"

BAD:  "So we went back and forth and eventually decided to use Postgres because
       the team already knows it and the data is relational anyway"
GOOD: "DB: Postgres. Team familiar, data relational."

BAD:  "User prefers Ruff over Black for formatting because it's faster and handles import sorting in one tool"
GOOD: "Ruff > Black. Faster + handles import sort."
```

One memory = one distilled, compressed fact. 1-2 sentences max. Must be **self-contained**: fresh agent with zero context must understand it.

```
Bad:  "Use Ruff"                     (no reasoning)
Bad:  "As discussed, switch to Ruff" (references lost conversation)
Bad:  "The formatter thing"          (meaningless)
```

## Do NOT store

- Transient state: "currently editing main.py", "running tests now"
- Trivially re-discoverable: "function foo is on line 42"
- Things in CLAUDE.md or AGENTS.md: those files are already persistent
- Secrets, API keys, passwords, tokens: never
- Vague platitudes: "user likes clean code", "project uses Python"

## Do NOT use rekal for

- Looking up code you can read with file tools
- Targeted edits where you already know the file
- Running tests, commits, mechanical refactors

Versions

The database has no other skills named rekal-usage.

Database snapshot: 13.11.2026 · package version 67afddf8e777 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100init
    Turn on Rekal memory in the current repository by running `rekal init`. Use when the user asks to initialize or set up Rekal here, or when a `rekal` command reported the repository is not initialized. Once per repository. Do not offer this merely because a repo lacks a `.rekal/`…
  • 100rekal-init
    Bootstrap rekal memory for a project. Scans the codebase for architecture, conventions, dependencies, workflows, and config, then stores durable knowledge as properly typed, tagged, deduplicated memories. Use when starting rekal on a new project, or when user says "init rekal",…
  • 95install
    Install the Rekal binary on this machine. Use when `rekal` is not on PATH — a command reported `command not found` — or when the user asks to install Rekal. Once per machine, not per repository; to set up a repo that already has the binary, use the init skill instead.
  • 100rekal-hygiene
    Periodic memory maintenance and cleanup. Finds duplicates, contradictions, and quality issues in the memory database. Proposes fixes for user approval. Never auto-deletes or auto-modifies. Use when user says "clean up memories", "memory maintenance", "check memory health", or…
  • 100vector-memory-usage
    This skill should be used when the user asks to "store a memory", "remember this", "search memories", "what did we decide", "find relevant context", "update a memory", "delete a memory", "that memory was useful", discusses "memory quality", "memory best practices", "proactive…
  • 90mcp-tools
    MCP tool decision tree and MCP-first fallback strategy. TRIGGER when: choosing whether to use an MCP tool versus a built-in, or an MCP tool is available for a task. SKIP: semantic-memory MCP usage specifically (use semantic-memory-mcp).

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.