remember

Session Cartographer

Reinstate context and work across sessions. Return to a line of thought, recover why a decision was made, or bring an insight from another conversation into the task at hand.

Context accumulates through the work itself. Cartographer makes captured activity and retained conversations searchable, so you can recover the context a question calls for, whenever it arises. Follow an idea across sessions, revisit an earlier investigation, and connect work whose relationship only becomes apparent later. You can work organically without preparing a starting context for every future session.

Claude Code and Codex contribute to the same local history and can recall each other's work; a read-only adapter brings Hermes history into the corpus too. Use /remember to find the earlier reasoning and follow it back to its source conversation, or browse the Explorer to reconnect with a thread of work.

Download a release · Setup guide · Changelog · Related projects

One day of recorded work: 51 tasks across nine projects. Project names are randomized for this screenshot.

Capture requires no LLM, and keyword recall needs no server. Semantic search and the Explorer are optional. The default setup keeps your history on your machine.

What you can do

These are Claude Code command names. In Codex, invoke the corresponding skill, for example $session-cartographer:remember or $session-cartographer:turbo, and describe the query or action. Project orientation replaces the retired Cartographer /focus skill.

Additional skills: Codex's $session-cartographer:setup diagnoses local semantic service access; /trustmap proposes Claude Code auto-mode environment settings from recorded usage. See auto-mode guidance.

Install

Download and extract session-cartographer-<version>.tar.gz from Releases, keeping the extracted directory in a stable location. One bundle supports both agents. Run the commands for your agent from that directory:

# Codex
codex plugin marketplace add "$PWD"
codex plugin add session-cartographer@session-cartographer

# Claude Code
claude plugin marketplace add "$PWD"
claude plugin install session-cartographer@session-cartographer

A source checkout can be registered with the same commands.

Codex hook approval: launch the Codex CLI, run /hooks, select Session Cartographer, and approve its hook definitions. Repeat when an update changes those definitions. Start a fresh task/session after installation or approval.

Choose your history location. The corpus defaults to ~/Documents/dev. Set CARTOGRAPHER_DEV_DIR in the environment used by your agent if your workspace lives elsewhere. File edits, commands, and Git commit capture require the opt-in CARTOGRAPHER_LOG_TOOL_USE=true. Logs can contain verbatim prompts and command lines; keep them out of version control.

Read Adopting Cartographer for corpus ownership, project aliases, privacy, and resource use. Release installation covers bundle verification and upgrades.

Optional semantic search

Keyword search works immediately against captured events. Add local Qdrant and an embedding server to search by meaning and recall indexed conversation turns. Follow Setup; no Docker is required. In Codex, use $session-cartographer:setup to diagnose access and request the necessary loopback permissions. A sandbox-denied request does not establish that a service is down.

Optional Explorer

From a source checkout:

npm ci --prefix explorer
npm run dev --prefix explorer

In a release bundle, the Explorer directory is plugins/session-cartographer/explorer; use that path instead. Open 127.0.0.1:2527, or use /carto after installing its dependencies. The UI binds to loopback only.

Timeline, search, sessions, and transcripts work without Turbo. The Memory Desk uses the managed Turbo backend and offers Start, Enable, or Refresh Turbo when needed. Opening the page directly does not start that backend.

Everyday use

Start with the context you need now: a decision to revisit, an investigation to resume, or an idea you remember exploring elsewhere. Ask /remember a concrete question, then narrow by project or date when useful:

/remember why did we change the retry policy
/remember --project my-app
/remember deployment --project my-app --since 7d

Search summaries are intentionally short. Follow the transcript to recover the conversation, or fetch complete event records from a checkout:

bash scripts/cartographer-search.sh "retry policy" --project my-app
bash scripts/cartographer-search.sh "lookup" --get evt-abc,evt-def

Repeated searches in one session suppress previously served IDs; --all includes them again. --transcript adds a raw-text fallback for conversations that have not been semantically indexed. For older material, scope the date window rather than treating an absent top result as proof that the history is missing.

For standing questions about the overall work, .carto/profile.md is a derived corpus summary. Rebuild it with node scripts/build-profile.js. Project aliases, bounded feeds for other agents, and briefings are described in Project Registry & Briefings.

Memory Desk and digests

Real recorded activity, with project and file names replaced for these screenshots.

The Explorer's Memory Desk is an evolving workspace for returning to tasks and inspecting their evidence. It includes:

• A shared time range, project and text filters, and saved return points.
• Task and file browsing, linked activity charts, and transcript navigation.
• Current-file previews and Git diffs bounded by a session's recorded activity.
• Recall, showing searches, ranked results, and explicitly marked uses.
• Day, grouping a local calendar day's work by project and checking commits against Git, with a copyable Markdown receipt.

Session and file links preserve the selected context. File content is current; diff boundaries use commit times and can include other sessions' changes. Recent activity is evidence of an event, not proof that an agent is still running. See the work desk and Memory link reference.

The same digests are available without the UI:

node sc