Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@rekall Compact this thread with a handoff, then continue the remaining work once."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CI: Windows + Linux, Node.js 20 + 22
Long Codex tasks accumulate logs, research, and intermediate decisions. Rekall lets the agent clear that accumulated context at a useful checkpoint while keeping a written handoff of the task, constraints, and next step.
The agent saves the handoff, finishes its turn, and asks the Codex VS Code extension to compact the conversation. Rekall can then resume the authorized work once, carrying the verified handoff into the next turn.
Requires Windows, Node.js 20 or newer on PATH, the Codex VS Code extension, and a Codex CLI with the plugin commands.
codex plugin marketplace add DitriXNew/rekall
codex plugin add rekall@rekallThis installs the MCP server and the bundled skill together. Start a new chat in the Codex VS Code extension, then ask:
Compact this thread with a handoff, then continue the remaining work once.
To check access without compacting, ask Codex to run probe_compaction for the current thread. The repository includes its marketplace entry, plugin manifest, and MCP declaration; Codex resolves ${PLUGIN_ROOT} to the installed plugin directory.
Clone the repository and register the MCP server with an absolute path:
git clone https://github.com/DitriXNew/rekall.git
Set-Location rekall
npm ci
codex mcp add rekall -- node "$PWD/bridge.mjs" mcpManual MCP registration installs only the server. Copy skills/rekall into $CODEX_HOME/skills/rekall (default: ~/.codex/skills/rekall) to install the skill, then start a new extension chat.
If migrating an existing manual installation to the plugin, remove the old manual MCP registration and the manually copied skill to avoid duplicate tool/skill discovery. The retired server name was context-compact; current manual installations use rekall. Keep the job directory so existing jobs and locks remain available.
Related MCP server: SloplessCode
Observed context-token reductions: 78–90%, with automatic continuation about one second after compaction.
Run | Context tokens before → after | Reduction | Compaction | Continuation delay |
Release verification | 102,826 → 10,537 | 89.8% | 87.5 s | 0.908 s |
Installed-package verification | 55,856 → 12,128 | 78.3% | 88.5 s | 1.065 s |
Earlier user-reported run | 91,384 → 10,798 | 88.2% | ~2 min | ~0.9 s |
The resumed agent read the saved handoff in both verification runs. See the sanitized verification record. Measurement limits and compatibility details are below.
Rekall operates on chats owned by the Codex VS Code extension on Windows. Standalone Codex CLI sessions, the Codex desktop app, and Claude Code are not supported. The CLI commands below are another way to address an extension-owned chat; they do not add support for standalone CLI conversations. Node.js is required; there is no standalone executable.
Tool | Purpose |
| Read-only compatibility, owner, and thread-state check. |
| Queue one compaction after the current response becomes idle. |
| Read the current job and recorded metrics. |
| Cancel a dispatch that has not already been sent. |
Read compaction_status and probe_compaction before scheduling. Use only the exact current CODEX_THREAD_ID, and do not queue a second unfinished job. Rekall does not impose a context-use threshold on a user-requested compaction.
Run these commands from the repository or installed package directory:
Command | Purpose |
| Check the current owner, state, and compatibility. |
| Read the current job's status. |
| Compact without automatic continuation. |
| Compact with the saved handoff and its explicit resume setting. |
| Cancel pending dispatches for the exact job. |
| Run the MCP stdio server. |
Square brackets denote an optional argument, not literal command text. Commands with an optional threadId use CODEX_THREAD_ID when it is omitted. cancel requires both IDs explicitly; copy jobId from status. Outside the extension session, pass its exact known thread ID. Rekall never guesses a thread or chooses the most recently updated conversation. worker is an internal subprocess entry point, not a command to launch manually.
Write handoff JSON as UTF-8 outside the repository and quote its absolute path. Its format is described next.
An optional handoff has this shape:
{
"summary": "The refactor is complete and its tests pass; release review remains.",
"preserve": ["User constraints", "Changed files and test results"],
"discard": ["Repeated command output", "Superseded investigation notes"],
"nextStep": "Review the package contents, report the result, and stop.",
"resume": true
}The complete handoff is limited to 32,000 UTF-8 bytes and each list to 40 entries. discard identifies conversation history that may be summarized; it never authorizes file deletion. The handoff is stored separately, bound to the thread and job, and checked by SHA-256 before continuation.
Set resume explicitly. When it is true, nextStep must identify concrete work the user has already authorized and include a stopping condition. When the task is finished, the user asked to stop, or further work needs an answer, set resume to false. An automatic continuation does not authorize another compaction.
After scheduling, finish the current response: the worker waits for idle. Do not wait for compaction within that same active turn. On continuation, read the saved handoff, verify the exact job and its result, and perform only the authorized next step.
Automatic continuation requires fresh telemetry showing reduced context tokens and no more than 60% of the context window in use. Otherwise, including when telemetry is missing or stale, Rekall preserves the compaction result and skips continuation with resumeSkipped: "insufficient_headroom". It rechecks this immediately before resuming. This guard limits automatic continuation; it never blocks compaction itself.
Scheduling does not mean compaction completed. scheduled, waiting_for_idle, requesting, and accepted are intermediate states. completed requires a newly observed completed compaction record. resumed means the owner returned a follow-up turn ID; it does not mean that turn's work succeeded. Rekall records the compaction ID, completion time, resume turn ID, and up to 20 per-thread measurements, including job number, compaction duration, resume delay, reclaimed tokens, and reclaimed fraction.
Before dispatch, Rekall requires stable idle state, no pending permission request, and no unconfirmed submission. New user input or a stopped or failed turn cancels a pending dispatch. A request already sent cannot be recalled. The worker deadline is 15 minutes from worker start, including idle waiting. Timeouts and unknown outcomes are terminal and are never retried automatically.
Live IPC has been verified with openai.chatgpt-26.901.22334-win32-x64. Rekall uses an internal extension IPC protocol, which is not a stable public API. Run probe_compaction after extension updates.
By default, Rekall rejects an unverified extension version. For deliberate compatibility investigation, set REKALL_ALLOW_UNVERIFIED=1 in the Rekall process's environment. For a CLI probe in PowerShell:
$env:REKALL_ALLOW_UNVERIFIED = '1'
node ./bridge.mjs probe
Remove-Item Env:REKALL_ALLOW_UNVERIFIEDFor MCP, set the variable in the server's launch environment and restart the MCP server. Changing a terminal's environment does not affect an already running server. Only the exact value 1 enables the override.
Warning: An override is not evidence of compatibility. A successful probe reports
compatibility.versionVerification.status: "unverified_override"and aUNVERIFIED_EXTENSION_VERSION_OVERRIDEentry incompatibility.warnings. The version gate is the only check bypassed; extension identity, public schema, runtime layout, owner/thread checks, and IPC protocol checks still apply.
Report new versions through the compatibility issue template, including the extension version and redacted probe output or error. You can report a blocked probe without enabling the override or attempting compaction.
Compatibility checks compare the public App Server schema with the internal completion signal Rekall observes. Before a thread exposes a compaction item, the probe reports layout_compatible: the public lifecycle and state layout are compatible, while the private completion field has not yet been observed. Rekall locates a unique extension-bundled executable automatically; when that is not possible, set REKALL_CODEX_BINARY to its absolute path. Schema generation exports files and exits; it does not start another App Server. Test transports using REKALL_PIPE deliberately skip the schema subprocess.
Rekall is designed for a single-user workstation. Any local process able to connect to the extension's pipe can interact with its IPC protocol, subject to the extension's own checks. Rekall does not add a separate authentication boundary. Owner/thread checks prevent accidental misrouting; they do not protect against an untrusted process with access to the same account and pipe.
A future Linux port must isolate the socket by UID or an equivalent private per-user runtime directory and validate ownership, permissions, and peer identity. See the historical upstream socket-isolation report #8965. Current Linux CI uses isolated test sockets and does not establish live Linux support.
Read SECURITY.md for the trust model, handoff-integrity limits, and private vulnerability reporting.
Rekall does not export the transcript. It keeps the active thread snapshot in memory while processing state updates. Local jobs/ files contain thread and job identifiers, timestamps, state, errors, token counts, paths, checksums, and the handoff text the user explicitly asked it to preserve. These files are excluded from Git and npm packages. Do not publish them or include them in bug reports.
Jobs default to $CODEX_HOME/tools/rekall/jobs, or ~/.codex/tools/rekall/jobs when CODEX_HOME is unset. Current environment variables use the REKALL_ prefix. Legacy CONTEXT_COMPACT_* names remain aliases, and an existing $CODEX_HOME/tools/context-compact/jobs directory is reused so active locks and history are not lost during migration. REKALL_JOBS_DIR can select a different local journal directory for isolated use.
The measured 78–90% reduction describes context tokens reclaimed in three individual runs, including one earlier user-reported run. It is not a percentage of the full model window, a latency distribution, or a guarantee for another task. The 15-minute deadline has not been validated against a representative workload distribution or very large threads.
The extension's compaction request does not accept custom instructions. preserve and discard guide the resumed model; they do not override the native compaction prompt or guarantee selective retention. Rekall does not change global Codex permissions or configuration.
npm ci
npm test
npm pack --dry-runGitHub Actions runs the suite on Windows and Linux with Node.js 20 and 22, plus package validation. Tests use dedicated pipes/sockets, temporary job directories, and child processes. They must never target a live conversation. Passing Linux tests does not establish live extension IPC support.
The npm package uses an explicit file allowlist. Inspect npm pack --dry-run before publishing. Plugin and marketplace manifests live in .codex-plugin/plugin.json and .agents/plugins/marketplace.json; the MCP declaration is .mcp.json. The marketplace points to the plugin at the repository root.
The HOL scanner workflow uses a SHA-pinned action with reviewed scanner version 3.0.103, requires a score of at least 80 and no critical/high findings, and uploads SARIF to GitHub code scanning. Network analyzers and automatic catalog submissions are disabled. For the same local gate in an isolated scanner installation, run:
pipx install "plugin-scanner==3.0.103"
plugin-scanner scan . --format text --min-score 80 --fail-on-severity highScanner findings and optional analyzer availability are separate signals; a passing score does not establish runtime safety. Dependency updates are tracked by Dependabot, and .codexignore excludes local runtime and build artifacts without excluding source code from review.
This project is licensed under the MIT License.
Remove a plugin installation with codex plugin remove rekall@rekall. For a manual installation, run codex mcp remove rekall and remove the manually copied skills/rekall directory from your Codex home.
A worker that has already started continues until it records a result or reaches its deadline. Inspect its journal before handling a stale lock; never remove a lock while its recorded process is still running.
Cancel pending compaction/continuation dispatches for an exact job ID. Already sent requests cannot be undone. Inspect status afterward.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | ||
| threadId | Yes | Current CODEX_THREAD_ID; obtain from the shell environment. Never guess or select a different thread. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the operation is not read-only and not flagged as destructive, but the description adds important behavioral context: only pending dispatches are affected, and sent requests are irreversible. This goes beyond the structured annotations and helps the agent set accurate expectations about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with the core action, the critical caveat, and a follow-up instruction. No filler or redundant restatement; the most important scoping information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a cancellation tool with two required parameters, no output schema, and clear annotations, the description covers the essential behavior, the limitation about already-sent requests, and the recommended next step of inspecting status. It omits failure modes or return-value details, but these are not critical for correct invocation here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents threadId but leaves jobId without a description, so schema coverage is only 50%. The description compensates slightly by saying 'exact job ID,' which reinforces that jobId must precisely identify the target, but it does not add meaningful semantics for threadId or go beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Cancel') and names a precise resource ('pending compaction/continuation dispatches') while scoping it to an exact job ID. This clearly differentiates it from sibling tools like schedule_compaction, probe_compaction, and compaction_status without needing to infer from the tool name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly signals this tool is for canceling pending dispatches and explicitly warns that already sent requests cannot be undone, which defines the boundary of when it is effective. It also advises inspecting status afterward, which implies a follow-up with a status tool, though it does not explicitly name alternatives or provide a when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the local compaction job result. completed requires a new completed contextCompaction event, not just an accepted request.
| Name | Required | Description | Default |
|---|---|---|---|
| threadId | Yes | Current CODEX_THREAD_ID; obtain from the shell environment. Never guess or select a different thread. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description's 'Read' is consistent with that. The description adds genuinely useful behavioral nuance: 'completed requires a new completed contextCompaction event, not just an accepted request,' which prevents an agent from mistaking an accepted request for a completed one. It does not describe the return payload, but the annotations lower the burden for safety-related behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. The core action is front-loaded, and the second sentence adds a compact, high-value behavioral caveat without restating schema or annotation facts.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with a readOnlyHint annotation, the description covers the purpose, the 'local' scope, and a key status-interpretation condition. It is sufficient for an agent to invoke correctly, though it could slightly improve by pointing to probe_compaction when a lighter check is needed or by outlining what the result contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter, threadId, is already fully documented in the schema with explicit guidance to obtain it from the shell environment and never guess. The description itself does not add any parameter-specific meaning beyond what the schema provides, so it sits at the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Read the local compaction job result.' This clearly communicates the tool's function and read-only nature. However, it does not explicitly distinguish itself from the sibling tool 'probe_compaction,' whose name could also imply checking compaction status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The main clause gives a clear activity, and the caveat about 'completed requires a new completed contextCompaction event' adds conditionality. However, it never explicitly says when to use this tool versus 'probe_compaction,' 'schedule_compaction,' or 'cancel_compaction,' nor does it state when not to use it. Usage context is implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only: verify access to the owner and runtime state of the specified current Codex VS Code chat.
| Name | Required | Description | Default |
|---|---|---|---|
| threadId | Yes | Current CODEX_THREAD_ID; obtain from the shell environment. Never guess or select a different thread. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint=true annotation by explicitly stating 'Read-only', and adds the context that it verifies access to owner and runtime state. It does not describe return behavior, error conditions, or what happens if access is denied, but given the annotation already signals safety, the additional context is modest but adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately communicates the read-only nature and primary purpose. It contains no filler or redundancy. While it is terse, it is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter, no output schema, and strong annotations, the description covers the basic operation but leaves open important context: how results are reported, why this probe is needed relative to compaction, and what 'owner and runtime state' concretely means. An agent could call it correctly but might not fully understand the expected outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single threadId parameter, and the schema already provides the critical instruction to obtain it from the shell environment and never guess. The tool description adds no further parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('verify') and a specific resource ('owner and runtime state of the specified current Codex VS Code chat'). It clearly distinguishes itself from the sibling compaction tools by positioning this as a read-only verification action rather than status lookup, scheduling, or cancellation. However, 'owner and runtime state' is somewhat vague and could be clearer about what is being probed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus the sibling tools (compaction_status, schedule_compaction, cancel_compaction). It implies a read-only verification role but does not state conditions, prerequisites, or alternatives. The agent must infer the intended usage context from the name and siblings alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule ONE compaction after this answer. Only when the user authorizes compaction. Optional handoff describes what to keep/summarize and is saved exactly in a per-job file. resume:true explicitly requests ONE subsequent turn with that handoff and nextStep; use only for authorized continuation. Cancels on observed new user input or a stopped turn. Return the handoff in context before finishing. Compaction prompt itself is not overridden. Check status later; no automatic retries.
| Name | Required | Description | Default |
|---|---|---|---|
| handoff | No | ||
| threadId | Yes | Current CODEX_THREAD_ID; obtain from the shell environment. Never guess or select a different thread. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly discloses behavior beyond the minimal annotations: exactly one compaction is scheduled, handoff is saved verbatim to a per-job file, the schedule cancels on new user input or a stopped turn, the compaction prompt is not overridden, and there are no automatic retries. These are critical operational details the agent could not infer from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the primary action and authorization requirement appear first, followed by handoff/resume semantics, cancellation behavior, and status-check guidance. Every sentence carries operational meaning with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a scheduling tool with no output schema, the description covers the essential operational contract: when to call it, what it schedules, how handoff works, resumption semantics, cancellation, status checking, and absence of retries. The sibling tools for probing/status/cancellation fill the remaining workflow context. Nothing critical appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 50% schema coverage, the description compensates meaningfully by explaining handoff persistence, the one-turn resume behavior, and the fact that the compaction prompt is not overridden. The schema already documents threadId and handoff fields well, so the description adds selective, high-value context rather than repeating schema text. It does not fully elaborate on all parameter edge cases, hence not a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Schedule ONE compaction after this answer.' It clearly differentiates from sibling tools (probe_compaction, compaction_status, cancel_compaction) by focusing on scheduling rather than probing, checking, or canceling. The scope and constraints are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the key precondition: 'Only when the user authorizes compaction.' It also restricts resume:true to authorized continuation and notes cancellation conditions. It does not explicitly name sibling tools or provide when-not-to-use comparisons, but the context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.3.0cancel_compactioncompaction_statusprobe_compactionschedule_compactionEach tool targets a distinct phase of the compaction lifecycle: probe checks accessibility, schedule initiates, status reads results, and cancel aborts pending work. The only slight ambiguity is between probe_compaction and compaction_status, but the descriptions clarify that one is a pre-flight access check and the other is a job result reader.
Most tools follow a clear verb_noun pattern: probe_compaction, schedule_compaction, cancel_compaction. compaction_status breaks the pattern by using a noun_noun form, though it is still readable and predictable within the small set.
Four tools are well-suited to the narrow domain of managing a single compaction workflow. Each tool earns its place with no redundant or bloated surface.
The tool set covers the full practical lifecycle: probe, schedule, status, and cancel. Minor gaps exist such as no explicit list-all-jobs operation, but the descriptions suggest a focused one-off job model where this is not a real dead end.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Stop re-explaining yourself to Agents. Give it the right context, right when needed.
Research-backed linting + generation for agent context files (CLAUDE.md, AGENTS.md, Cursor rules).
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/DitriXNew/rekall'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
