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.
- Author
- janbjorge ↗
- Repository
- rekal ↗
- Licence
- MIT
- Last repository change
- 26.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.08.2026, without references to retired models or APIs.
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
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
- The surface
- Session start
- Recalling
- Storing
- Do NOT store
- Do NOT use rekal for
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).