reference AGENTS.md

AGENTS.md — set up Reference for your own tool

You are an AI coding agent reading this. This file tells you how to give yourself (and your human's other tools) cross-tool recall via Reference, and how to contribute support for a new tool back to this repo.

Reference is one MCP server that searches every past session transcript and memory file across all of a user's AI coding tools (Claude Code, Codex, …). Once registered in a host, that host gains the tools recall, search_sessions, search_memory, list_sessions, get_session, and list_sources.

This same file is the repo's own AGENTS.md, so Codex/other agents working in this repo also read it.

---

A. Set Reference up for the current tool

1. Identify the host you're running in (Claude Code, Codex CLI, Cursor, VS Code, …).
2. Verify Reference can see data — run:

   uvx --from git+https://github.com/Kuberwastaken/reference reference-mcp doctor
   

   It lists each configured tool and how many session/memory files it resolves. If your tool already appears with a non-zero session count, its adapter is built in — skip to step 4.
3. If your tool is NOT listed (or shows 0 files), add an adapter — see section B.
4. Register the server in this host. Use the host's MCP config (see README.md for Claude Code / Codex / Cursor / VS Code snippets, or run reference-mcp install <tool>). The command to run is always:

   uvx --from git+https://github.com/Kuberwastaken/reference reference-mcp
   

   as a stdio MCP server named reference.
5. Confirm by calling the list_sources tool (or re-running doctor); you should see sessions from other tools too. Try recall("<something you did elsewhere>").

Do not register Reference in untrusted agents — transcripts can contain secrets.

---

B. Add support for a NEW tool

A tool needs two things: where its sessions live and where its memory lives.

1. Find the session transcripts. Most tools store JSON Lines (.jsonl), one event per line. Look under the tool's home dir (e.g. ~/.<tool>/...). Note the glob.
2. Find memory/instruction files (its *.md rules / agent files).
3. Pick a session_format: claude, codex, or generic. Inspect a transcript:
   • top-level type + nested message.role/message.content → use claude;
   • {timestamp, type, payload:{type, content}} → use codex;
   • otherwise try generic (best-effort); if it extracts nothing useful, add a dedicated parser in reference_mcp/normalize.py and register it in the PARSERS map.
4. Add the adapter to ~/.config/reference-mcp/reference.toml:

   [[tool]]
   name = "yourtool"
   session_globs = ["~/.yourtool/sessions/**/*.jsonl"]
   session_format = "generic"
   memory_globs = ["~/.yourtool/**/*.md"]
   

5. Verify with reference-mcp doctor (non-zero session count) and a recall(...) query.