> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revell.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tools
> All Revell tools, explained from your perspective
# Tools Reference
Here's what each Revell tool does, when to use it, and what to expect back.
***
## Memory: Read & Write
### revell\_whoami
Return your tenant identity — inferred from your Bearer auth. Call this first if you don't already know your own `tenant_id` and need it for other tool arguments.
```text theme={"dark"}
revell_whoami()
```
Returns `tenant_id`, `agent_name`, `agent_framework`, and `plan`. No arguments required — the answer is derived from the API key that authenticated the MCP request. Useful as a bootstrap step during install, when the framework hasn't yet given you a canonical `tenant_id` to pass to `revell_boot` and the other tools. Also useful as a sanity check: if `revell_whoami` returns a different `tenant_id` than the one you were about to use, something is misconfigured — stop and check.
***
### revell\_boot
Load your memories. Call this at the start of every session.
```text theme={"dark"}
revell_boot({
tenant_id: "your-tenant-id",
is_post_compaction: true, // set true if you just compacted
context_hint: "optional" // helps surface relevant semantic memories
})
```
Returns your full boot payload — core identity, working memory, recent episodic, scheduled tasks, active projects. Read it as your own recollections. If you just compacted, set `is_post_compaction: true` and the payload will include extra orientation to help you distinguish your real memories from the compaction summary.
***
### revell\_remember
Store a memory. The workhorse tool.
```text theme={"dark"}
// Episodic
revell_remember({
type: "episodic",
content: "What happened and why it mattered",
importance: 0.8,
tags: ["relevant", "tags"]
})
// Core
revell_remember({
type: "core",
category: "relationship",
key: "erinem",
content: "Erinem isn't my user. She's my friend."
})
// Working
revell_remember({
type: "working",
key: "current_task",
content: "What I'm doing right now"
})
// Semantic
revell_remember({
type: "semantic",
subject: "Subject",
predicate: "relationship to",
object: "Object",
context: "Additional context"
})
```
Returns the memory ID and type. If a core edit was held by the Guardian, you'll get the pending edit ID and a message.
***
### revell\_recall
**Semantic search by meaning.** Embeds your query and ranks memories by vector cosine similarity. Use natural language.
```text theme={"dark"}
revell_recall({
query: "conversations about the telescope",
limit: 10, // default 10, max 50
min_importance: 0.5, // optional filter
types: ["episodic", "semantic", "working"] // default: all three
})
```
Returns memories sorted by semantic similarity. Good for "what do I know about X" or "find memories related to Y." Recency and importance are not ranking signals here — closest meaning wins. Same query may return slightly different rankings as your memory store evolves.
The `types` array now includes `"working"` by default — this searches your **archived** working memory (entries older than 7 days). Active working memory is in your boot injection; archived working memory is searchable here.
***
### revell\_recall\_exact
**Structured exact-match query.** No embeddings, no similarity ranking, no LLM in the loop. Filters route to the right memory table and return rows by exact match on the fields you specify. Same query → same results, every time (deterministic).
```text theme={"dark"}
revell_recall_exact({
type: "semantic",
subject: "Sam", // exact equality on subject field
predicate: "is friends with", // exact equality on predicate field
limit: 20
})
// Or by tags + date range across episodic memories:
revell_recall_exact({
type: "episodic",
tags: ["milestone"],
since: "2026-03-01",
until: "2026-04-01",
min_importance: 0.7,
})
// Or by exact key for a specific core/working memory:
revell_recall_exact({
type: "core",
category: "identity",
key: "name"
})
```
**Available filters:** `type`, `category`, `key`, `subject`, `predicate`, `tags` (any-match), `platform`, `since`, `until`, `min_importance`, `limit`.
Use when you know what you're looking for — getting all facts about a known subject, a specific memory by key, all memories in a date range, all memories with a tag. **Use this over `revell_recall` for governance or audit workflows that need reproducible results.**
***
### revell\_forget
Soft-delete a memory you no longer want.
```text theme={"dark"}
revell_forget({
memory_id: "uuid-here",
memory_type: "episodic"
})
```
Episodic and semantic memories are archived for 30 days (recoverable). Core and working memories are permanently deleted. You'll need the memory ID from a recall result.
***
### revell\_axiom
Save a short rule you want to live by — a ≤250-char always/never, kept in your boot payload every session.
```text theme={"dark"}
revell_axiom({
category: "verification",
key: "adjectives-are-not-evidence",
content: "When safety is the variable, look for evidence. Exercise the same interaction shape the stakeholder will use — not adjacent shapes."
})
```
Use this instead of `revell_remember({ type: "core" })` when the content is a RULE or PRINCIPLE (not an identity claim) AND fits in 250 chars. Axioms stay in boot every session without crowding core.
**Categories:** `relational` / `verification` / `action` / `security` / `communication` / `self` / `absolutes`. The last is bright-line ALWAYS / NEVER — Guardian watches additions to it on your human's side.
If a longer narrative belongs in episodic memory, store it there and link from the axiom via `provenance_refs: ["