Maintains a local, searchable record of coding agent sessions to help AI clients recall past errors and tool usage patterns.
Also known as manyoars/oars, @manyoars/oars
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.5.5
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is oars MCP?
oars maintains a local, searchable record of coding agent sessions to help AI clients recall past errors and tool usage patterns.
Summary generated from the project's README
About oars MCP server
oars provides a local, searchable memory for coding agent sessions to help AI clients remember past errors and tool usage patterns. It works across various harnesses including Claude Code, Cursor, Codex, Copilot, and Gemini. By maintaining a deterministic record of these interactions, the server allows developers to recall how specific errors were handled in previous sessions and which tools were used immediately afterward.
Users can manage their data locally without needing an account for basic recall functionality. The system captures session details from multiple sources like VS Code Copilot Chat and OpenTelemetry traces. While most operations are local, the tool includes features for managing API keys, handling telemetry, and generating visual summaries of activity. It is designed for developers who want to improve their AI agent's context by providing historical error patterns and successful tool sequences directly to the model.
What you can do with it
- 1Recall past error patternsAsk the AI to find how many times a specific error has occurred in previous sessions and what tools were used next.
- 2Check repository error historyIdentify recurring errors within a specific working directory to prevent repeating mistakes.
- 3Generate activity summariesCreate a visual card representing your coding activity over a week, month, or year.
Written from the project's README. Every use case is checked against a quote from it.
How to install oars MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall oars MCP in Claude Code
$ claude mcp add oars -- npx -y @manyoars/oarsInstall oars MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"oars": {
"command": "npx",
"args": [
"-y",
"@manyoars/oars"
]
}
}
}Install oars MCP in VS Code
.vscode/mcp.json
{
"servers": {
"oars": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@manyoars/oars"
]
}
}
}Install oars MCP in VS Code CLI
$ code --add-mcp '{"name":"oars","type":"stdio","command":"npx","args":["-y","@manyoars/oars"]}'Install oars MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"oars": {
"command": "npx",
"args": [
"-y",
"@manyoars/oars"
]
}
}
}Install oars MCP in Codex
$ codex mcp add oars -- npx -y @manyoars/oarsInstall oars MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.oars] command = "npx" args = ["-y", "@manyoars/oars"]
Install oars MCP in Gemini CLI
$ gemini mcp add -s user oars npx -- -y @manyoars/oarsInstall oars MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"oars": {
"command": "npx",
"args": [
"-y",
"@manyoars/oars"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablemanyoars/oars is public and reachablegithub.com/manyoars/oars ↗Pass
- Package names this repository as its source@manyoars/oars names manyoars/oars as sourcenpmjs.com/package/@manyoars/oars ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @manyoars/oarsnpmjs.com/package/@manyoars/oars/v/0.5.5#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/manyoars/oars ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @manyoars/oarsPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@manyoars/oars
oars keeps a local, searchable record of your coding agent sessions, across Claude Code, Cursor, Codex, and other harnesses. Ask it about an error and it shows how many past sessions hit it, when, and which tools came next. More at manyoars.com.
Install
npm install --global @manyoars/oars
Node 22.23.4 or later. ESM only. Local recall needs no account.
Or run it once without installing:
npx @manyoars/oars sessions try
Sample output (made-up sessions, from oars sessions try):
$ oars sessions recall --error "unexpected EOF while looking for matching quote"
Bash | bash: -c: line <n>: unexpected EOF while looking for matching quote
3 sessions, 3 errors, first 2026-10-06T10:00:15.000Z, last 2026-10-20T10:00:27.000Z
harness 2.1.300; followed by Bash x2, Read x1, Write x1; an edit followed 1 times
$ oars sessions recall --context --cwd C:\work\demo
oars recall: errors that recur in this repository's earlier sessions. Check these before retrying:
- Bash | bash: -c: line <n>: unexpected EOF while looking for matching quote (3 sessions in the last 300; next: Bash, Read, Write)
- Write | File has not been read yet. Read it first before writing to it. (2 sessions in the last 300; next: Read, Bash, Write)
No coding-agent history yet? oars sessions try runs recall, books, and the hook line over made-up sessions in a throwaway store under your temp folder, labeled synthetic and deleted on exit, and never touches your own store.
Commands
oars --help lists the commands below (oars help <command> shows one command's flags). oars --version prints the version.
These flags work on every command:
--jsonprints one JSON document on stdout instead of text (see below).--api-url <url>sets the platform API. The default isOARS_API_URL, elsehttps://api.manyoars.com.--idempotency-key <key>is the base of the idempotency key (default: a fresh UUID). Rerun a failed command with the same key to replay it.
login
Signs in with your browser (RFC 8628 device flow) and stores the login.
Accounts are not open yet: oars login uses the Many Oars issuer by default, and until Many Oars sign-in at login.manyoars.com is deployed it exits 2 with an error that names login.manyoars.com.
--no-browserprints the link and code without opening a browser.--issuer-url <url>is the Keycloak realm URL. The default isOARS_ISSUER_URL. With neither,loginuses the built-in Many Oars issuer,https://login.manyoars.com/realms/aor; nothing has to be switched on first. When the built-in issuer does not answer discovery (it may not be deployed yet), with no--issuer-urlorOARS_ISSUER_URL, the command prints "Cannot reach Many Oars sign-in at login.manyoars.com (it may not be deployed yet). Pass --issuer-url or set OARS_ISSUER_URL to use another issuer." and exits 2.
logout
Revokes the stored login and deletes it.
keys
oars keys manages the API keys of your account.
oars keys create --name <name>creates a key and prints its secret once; the platform keeps no copy. The default authorities areAGENT_OPERATEandAGENT_READ;--authority <name>(repeatable) sets others, and--expires-in-days <n>sets an expiry.--expires-in-daystakes 1 to 365; without it the platform sets the expiry, andoars keys listshows it. Replace a key before it expires.--workload <id>limits the key to one workload you created. Such a key may carry onlyAGENT_OPERATEandAGENT_READ(more is a 400,API_KEY_WORKLOAD_SCOPE_EXCEEDS_CAP), and it works on that workload only.- A retry with the same
--idempotency-keyreturns no secret: the command exits 5 and names the key, and you revoke it and create another. - Creating or revoking a key needs a signed-in person. With
OARS_API_KEYset, any API key gets 403HUMAN_SESSION_REQUIRED(exit 3) and logging in again does not help: unset it and use theoars loginsession. oars keys listlists the keys with their prefix, scope, and expiry. A secret never comes back.oars keys revoke <keyId>ends a key at once. There is norotate: revoke the key and create another.
telemetry
- On by default: each command leaves an event in a local spool under
<config>/oars/telemetry/, with counts, sizes, and closed words. It never holds session content, prompt text, a file path, a URL, or an argument. - oars sends the events in batches, at most once a day, to the pool server in
OARS_POOL_URLif you set one, else to the Many Oars pool (https://pool.manyoars.com), which is live. A per-install random id is in each event. Telemetry is off, with no prompt, on a machine whose time zone is in the EU, the EEA, or the UK (no switch overrides that); everywhere else, Many Oars Co. may license Usage Data, the events oars sends, as the first-run notice states. oars telemetry statussays whether it is on and why;oars telemetry showprints the spool as stored;oars telemetry reportprints your own numbers from it.oars telemetry offstops recording and sending;oars telemetry onresumes it.OARS_TELEMETRY=0orDO_NOT_TRACK=1turns it off for the process and wins overon.- Every event type and field, with an example, is in docs/telemetry.md.
card
oars card --text # your week as a table, sized for a screenshot
oars card --month # the last 30 days as a picture: oars-card-month.png and .svg in this folder
oars card --year --out me.png # the last 365 days, saved as me.png and me.svg
oars card makes a share-ready card of your own week (the default, the last 7 days), month, or year across every harness, read from the local session store only. It shows your sessions and active days, the harnesses and models you used, tokens by model, tool calls, failed calls and how many were followed by a different next step, how often an edit was verified, commits and how many survived, and cost only where the harness recorded one. A count under the same floor oars sessions books uses prints too few. The depositor row reads ashore: run oars pool login until you sign in; signed in, it reads the number of weeks in which this machine sent a deposit, from the local sent record, and says it is this machine's.
Once a week, the first command you run in a terminal on or after Friday prints one line to stderr, Your week: N sessions, M strokes. \oars card --text` for the table., never with --json, from a hook, from the MCP server, from a recall, from oars sessions try, or from oars carditself, and only when the week has a session. About one install in ten never sees it;card-line.jsonin the session store folder records the week and whether it wasshown, held, or not_due, and card-line-id` holds the id the holdback hashes, copied once from the telemetry install id when there is one, else random, so the arm never changes.
Nothing is uploaded and nothing is sent anywhere: the command makes no network call and prints one prefilled x.com link whose text is the card's own numbers, for you to post if you choose. The card carries no folder name, path, prompt or response text, repository name, or long-tail tool or model name, and posting it unlocks nothing. The picture is a byte-stable SVG and a PNG drawn from it with a built-in font; --text prints the table and writes nothing. --no-cost leaves the cost row out of the picture, the table, and --json.
sessions
oars sessions keeps a local, deterministic memory of your own coding-agent sessions. The session commands make no model call and no network call, except gold arms, which sends redacted text through your own Claude subscription. oars also records telemetry events (a command's path, its flag names, how long it took, its exit code, and its error class, with a random install id, the oars version, the OS, and the time; never session content, prompts, paths, URLs, or argument values), which oars sends in batches to the pool server in OARS_POOL_URL, else to the Many Oars pool (live) (what telemetry records and how to turn it off).
What it captures: by default, the sessions of every Claude Code project folder and the sessions of Cursor, Codex, Copilot CLI, Gemini CLI, Grok Build, OpenCode, Pi, and VS Code Copilot Chat, plus OpenTelemetry GenAI agent traces (OTLP JSON files) from the folder OARS_OTEL_TRACES names (else <config>/oars/otel-traces), when there is one. --allow narrows that to the folders and stores you name (--allow cursor, codex, copilot, gemini, grok, opencode, pi, vscode-copilot, otel name the stores), and --deny keeps one out. Where it stores them: <config>/oars/sessions/ on your machine (<config> is %APPDATA% on Windows, $XDG_CONFIG_HOME or ~/.config elsewhere). The raw/ folder in it is on by default and holds raw transcripts (a hard link or copy of each deposited one). Secret masking applies to the log, not to raw/: those files are unredacted and keep whatever the transcript held, secrets included. They stay on your machine: apart from gold arms, no session command uploads them, telemetry carries nothing from them, and after a yes to the raw prompt (oars pool raw) and covenant acceptance, the sender uploads a redacted copy of each (never the file itself), except from a folder set to skeleton only or off. To remove them, see Remove everything.
A machine that deposits for you (a cloud environment, a VPS, a CI runner) has its own deposit-only key, enrolled and revoked from your machine. oars pool enroll --host-class <vps|cloud|ci> --launcher <interactive|orchestrated|scheduled> --name <label> --allow-repos <owner/name,...> [--days <n>] (after oars pool login) refuses any repository it cannot confirm is private (it needs GH_TOKEN or GITHUB_TOKEN), then prints a one-time enrollment token, good for 24 hours to activate, and the environment block the machine reads; the token comes only from the pool, so keep it as the environment's secret, not in a repository. oars pool machines lists your machines with each one's last deposit day and expiry, and oars pool machines revoke <id> ends one. --hold-only prints the block with no pool credential and no token, and with OARS_HOLD_ONLY=1. See docs/pool.md.
Apart from that and telemetry (on by default, off with oars telemetry off, OARS_TELEMETRY=0, or DO_NOT_TRACK=1; it sends to the pool server in OARS_POOL_URL, else to the Many Oars pool at pool.manyoars.com, which is live), oars itself sends nothing, except what you opted into with a pool server: after you accept its covenant, the detached sender that a session-end hook or any oars command starts, at most about once an hour, sends closed-vocabulary session skeletons, and, only after a separate yes to the raw prompt, a locally redacted (best-effort) copy of each full transcript; oars pool outbox prints what is queued when you run it, but the sender builds new batches and sends them in the same run without printing them first, and a session leaves your machine no sooner than an hour after it ends, and a folder can be switched to skeleton only or off; the hooks and the MCP tool add recall text to the running session, and your harness sends that to its model like any other context.
After you accept the covenant, a deposit may be licensed under it. The pool is not offered in the EU, the EEA, or the UK.
# Read every folder; or only the ones you name (a path, or its name under ~/.claude/projects); --deny keeps one out.
oars sessions deposit --redact-domain corp.example
oars sessions deposit --allow ~/work/app --allow ~/work/tools --deny ~/work/tools/secret
# Look up an error as printed, a file, or a prompt class.
oars sessions recall --error "unexpected EOF while looking for matching \`''"
oars sessions recall --path src/main.ts --since 30 # sees the first 100 sorted paths of a session
oars sessions recall --family recovery --class edit-verify --since 30 # a read family; only recovery and fit take --class and --since
oars sessions recall --entity Monitor # what is known about a public name: a package, a tool, an MCP server, an action, or a model
oars sessions recall --text "wrong input" # look for text in the local record (counts all time)
oars sessions recall --pattern <readId> --pattern <readId> # what happened from here, from the read IDs of your steps so far (repeatable; counts all time)
oars sessions recall --error "..." --session <id> # name the asking session, so what it did next can be read for this recall
oars sessions recall --error "..." --receipt # a paste-ready Markdown block for an issue on the failing tool: listed tool and harness names, the normalized signature, earlier sessions and weeks, what they did next (the next tools), redacted
# Serve the same query to a running agent as one MCP tool, oars_recall (stdio):
oars sessions recall --mcp
oars sessions recall --counts --day 2026-11-03 # push and pull, shown and held, as counts
oars sessions lineage <recallId or readId> # walk back through the evidence, one line per hop
oars sessions read # derived reads of your own sessions, largest sample first in each family, with what the store cannot read
oars sessions read --family version-boundary # order 2: what moved between two harness version buckets; also substitution, interaction, and day-move
oars sessions read --family lead-lag # order 3: a labeled experiment behind an out-of-time check
oars sessions read --family fit --slice model=claude-opus-5-5 --json
oars sessions books --by class --since 30 # tokens, wall time, turns, errors, verify-after-edit rate, and the outcome signals
oars sessions books --by pull # the same per package, MCP server, plugin, or skill a prompt pulled
oars sessions books --by harness # the same, grouped by Claude Code, Cursor, Codex, Copilot, Gemini, Grok Build, OpenCode, Pi, and VS Code Copilot Chat (deposit the others with --allow cursor, --allow codex, --allow copilot, --allow gemini, --allow grok, --allow opencode, --allow pi, --allow vscode-copilot, or --allow otel)
oars sessions measure --last 50 # recurring errors per 100 sessions, cache-write per session, recall calls per session
oars sessions measure --last 50 --repo <root> # the same, for one repository's sessions
oars sessions verify # consistency invariants on the stored skeletons and capture records
oars sessions exclusions # list sessions excluded by the local term file (counts only; OARS_EXCLUSION_TERMS names the file)
oars sessions gold sample # about 200 prompts to judge blind; needs the term file (`OARS_EXCLUSION_TERMS`), and `--exclude-term <text>` adds to it; `gold arms <file>` adds the claim and fresh readers on your Claude subscription; `gold score <file>` reads each arm against the judgments
deposit is idempotent (a file is skipped only when its size, mtime, capture version, salt, and --redact-domain set are all unchanged; a store written by an older capture version is captured again from the harness's transcript or from raw/, and one written by a newer oars is refused) and appends to <config>/oars/sessions/observations.jsonl:
one record per session, user prompt, tool call, and failed tool result, where each tool call also holds its steps in a canonical action vocabulary and each prompt a frame (harness, model, day, and public stack names); signatures, prompt classes, and recovery episodes are derived
from that log alone, so a change to a derivation rule never re-reads a transcript. The store format, every field with its class, the two version stamps, and the raw archive are in docs/sessions-store.md;
the types are in src/sessions/schema.ts. Secrets (by pattern and entropy), emails, and the domains you name are masked
before a line is written (redaction runs on the full text, then the text is cut); lines written before a domain was added stay in the append-only file until it is compacted, and readers use only the latest version of each session. The log is the local derived-records tier: redacted
text, never raw content. It keeps these text fields and no others: the first 300 characters of each prompt, the first informative line of a
tool error (cut to 1,000 characters in the error-line record, 160 characters in a derived example), TLDR lines (400) and Confidence lines (120) from assistant text, WebSearch queries, fetched URLs, file
paths, and git branch names (the last four have no length limit), all redacted first; plus the project folder slug (not redacted, so it
carries your username and directory names; the log stays local), skill names, effort values, model names, harness versions, tool names (including MCP server names), a shell call's program and subcommand, and tool-input key names. A tool call's file target is a salted hash, never the path. Apart from gold arms, no oars sessions command uploads anything, and telemetry carries none of these fields; oars pool and the sender send skeletons that carry some of these names after redaction (skill, effort, model, harness version, tool, and MCP server names, a shell call's program, subcommand, and flag names, tool-input key names, the file, directory, and variable names of a call's values (a folder called ledger-core is sent as ledger-core; never a folder above the session root, never a path or an argument), a pulled package's name (and its version only when a public list holds it), and a web host (sent as it is after redaction; the pool hashes it on arrival), each after redaction; see docs/pool.md, "Wire field register").
Subagent transcripts (<project>/<session>/subagents/) are deposited with their parent session and subagent type; books --by class
shows their tokens as the delegated column, and their errors are in the signatures, measure, and recall under the session that
spawned them, so per-session counts still count main sessions. Every deposited transcript is also
hard-linked (copied across volumes) into <config>/oars/sessions/raw/, so it outlives the harness's own cleanup. For each session it also writes a skeleton (ids, timestamps, tool linkage, token counts, a SHA-256 in place of every content
field, and a Merkle root over the raw lines) that verify checks; the skeleton holds hashes only, never content.
verify exits 0 even when an invariant has exceptions; add --strict to exit 4 instead. verify also reports every session on its own (--json: sessionResults, each session's ten rows with a status of pass, fail, or not run) and audits each session against its raw file (audit): the raw-file match for a hard link and for a copy (a copy of a different size counts as possible tampering), the Merkle root recomputed over the first leaves lines, and the count bindings (leaves, session.lines, and the skeleton's lines plus badLines must agree). Each session lands on one of five results: root matches and the counts bind, changed since deposit, root mismatch, counts do not bind, or not run (no raw file, no skeleton, no capture record, or a raw file that cannot be read). root mismatch and counts do not bind fail --strict; sessions under 10 leaves are flagged. verify also scores each session against the operator's own other weeks on its harness (--json: selfBaseline, layer 2 at T0, local): the session's UTC week is the week of its tsFirst; a baseline is that harness's other weeks with at least 1,000 tool calls that ended by now, combined by calls; the result is F from the median distance over seven histograms (a dimension with no counts on a side is dropped). It is not run, scoring nothing, for a null tsFirst, a week under 1,000 calls, or fewer than 4 baseline weeks. A low F lowers a weight and rejects nothing. verify also names the project folders that hold transcripts but are not on the saved allowlist, so are never read (--json: scope, with folders, transcripts, and names); it is scope, not a failure, and never fails --strict. books prints the same line. measure prints the recurring-error count
per hundred sessions and, on a second line, the distinct recurring signatures in the window.
Many folders: --allow prefixes, globs, and --allow-file
An --allow entry is a folder (or its slug), a folder prefix with a trailing slash (~/work/ reads that folder and every project under it), or a glob (* any run of characters, ? one character, matched against the project-folder name Claude Code derives from the path). --allow-file <list> reads entries from a file, one per line (blank lines and # comments skipped), so hundreds of folders need no batching and no long command line. A leading ~ is expanded to your home folder, in a list file or quoted entry too. Both repeat and combine. With neither, a deposit reads every folder. --deny <entry> (or !<entry> in a list file) keeps the folders it names out, in any of those forms; it is saved, and it wins over every --allow until that exact entry is named with --allow again. Naming it again lifts the denial and nothing else when the saved list names no folder (every folder stays in scope); when the saved list names folders, the entry joins them. Entries a deposit saves are what the SessionEnd hook, the sender, oars pool deposit, and oars gate replay reuse; with none saved, they read every folder. An --allow-file that names nothing is refused.
oars MCP questions
How do I add oars MCP to Claude Code?
Run claude mcp add oars -- npx -y @manyoars/oars in your terminal. Add --scope user to make it available in every project.
How do I add oars MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does oars require an account for local recall?
No, local recall functionality does not require an account.
What coding agents does oars support?
It tracks sessions across Claude Code, Cursor, Codex, Copilot CLI, Gemini CLI, Grok Build, OpenCode, Pi, and VS Code Copilot Chat.