Monet

io.github.team-monetPublished by GitHub account team-monetv1.12.0Updated Nov 6, 2026

Local-first, state-centric memory for coding agents. MCP server + CLI.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Local-first memory server for coding agents that stores principles, rules and corrections and serves them back while the agent works.

What you can do
  • Store, search and read durable memories as pointer cards, then fetch full concept bodies and synthesize them
  • Declare, ratify and look up rules, stages and principles, and record whether an action followed them
  • Track session work with checkpoints and workstreams, and inbox items that fall outside the current task
  • Curate the store: flag and resolve contradictions, detach wrongly merged observations, retire or restore memories
  • Organize memories into per-project circles and reassign, merge, archive or rename them
  • Orient at session start with a context call that resolves the circle and names stages needing rule lookups
When to use it
Useful for coding agents that should keep durable project knowledge, user-stated rules and corrections across sessions, and apply rules at the moment they bind. Best for people who want memory kept entirely on their own machine rather than in a hosted service.
Requirements
Runs as a local stdio process installed from the npm package, so Node.js is needed. Storage defaults to a home-directory store and can be relocated with the MONET_STORAGE_DIR environment variable. No account, API key or network access is required; embeddings run on-device.
Before you install
The server writes to and curates a persistent local store: memories can be stored, retired, merged, moved between circles and have contradictions resolved, and some records are first-write-wins. The README's setup path asks an agent to fetch and follow a remote install document, which is worth reviewing before running. A background model process is started locally and serializes requests, so long writes can block other sessions.

Installation

In SourceWeft

  1. Open Monet in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

monet

Memory should change what your agent does.

[npm] [MCP Registry] [Website]

🌐 team-monet.com · listed on the MCP Registry

Monet is local-first memory for coding agents, built for the outcome you meant. It keeps what you and your team actually want — principles, rules, corrections — and delivers it while the agent works: principles always on, rules read at the moment they bind, corrections recorded so they never need making twice. It runs 100% locally (SQLite + on-device embeddings) and speaks MCP.

Get started — let your agent set it up

The easiest way to use Monet is to let your agent install and wire it for you. Paste one line into Claude Code (more agents coming soon):

Set up Monet for all my projects: read https://raw.githubusercontent.com/team-monet/monet/main/harness/bootstrap/install.md and follow it, checking with me at each step.

Your agent installs Monet, wires up the MCP server, and pulls in a memory-aware agent team — no manual config, no environment variables. That's the with-monet harness, which lives in harness/ in the Monet repo, and it's the recommended path.

⭐ If Monet helps, star Monet on GitHub — it's the best way to support the project.

Zero config

Monet keeps one local store at ~/.monet and automatically organizes each project into its own circle — nothing to set up. Everything stays on your machine.

Run as many agent sessions as you like: they share one copy of the embedding model, so another session costs tens of megabytes rather than gigabytes. The first session that needs the model starts one background process (model-host) to hold it. It is reachable only by your own user, never over the network, and it exits by itself after a few idle minutes; the next session that needs it starts it again. It works through one request at a time, so a very long write makes other sessions wait. If it ever stops answering, the waiting call fails after ten minutes and says which process to end.

See your memory — monet dashboard

Run one command to open a local web view of your Monet memory as an explorable, force-directed graph:

bash
monet dashboard

It opens in your browser automatically — if it doesn't (some Windows/headless setups), the terminal prints the URL (http://localhost:7373) and the store path; just visit that URL. The Graph tab is the main view: nodes are concepts (colored by kind, sized by importance), edges are the relationships between them, and a detail panel lets you read any concept's full body and evidence. The Concepts, Entities, Timeline, and Health tabs are sortable tables — Health surfaces contradictions, duplicates, and low-confidence concepts. If the graph looks empty, check the Store: line in the terminal: an empty graph usually means it's pointed at the wrong store (use -d) or the store is just new.

100% local. Fully offline. Strictly read-only. The server copies your store into a temporary snapshot on each request — the live database is never written to or locked. No network connections are made; run it with wifi off and the graph still renders.

bash
monet dashboard              # opens at http://localhost:7373monet dashboard -p 8080      # -p, --port <n>   custom portmonet dashboard -d ./path    # -d, --dir <path>  point at a specific store

Diagnose and repair an embedder store — monet doctor / monet repair

If Monet reports an embedder pin mismatch, an interrupted embedding migration, malformed vectors, or an unavailable local model, start with the read-only diagnostic command:

bash
monet doctormonet doctor --check-provider       # also load and probe the exact pinned providermonet doctor --dir ~/.monet --json  # machine-readable result; diagnostics stay on stderr

doctor prints the absolute database path, SQLite integrity and schema, the durable model pin, all four live embedding populations (including dimensions and malformed-row samples), any migration sentinel, and copy-paste next commands. It does not construct MonetCore or alter the database. A healthy diagnosis exits 0; a completed diagnosis that needs recovery or provider action exits 2; inspection failures exit 1. An unavailable provider is reported separately from store safety—for example, an unsupported hashing tokenizer or missing ONNX cache does not by itself mean the database is corrupt. For an ONNX or custom model ID whose shape cannot be proven from the pin alone, --check-provider can reconcile an otherwise unknown assessment only when the exact provider loads and every clean live population has the same matching vector width.

When the server will not start at all

A host that cannot start the server reports only that the connection closed — the transport does not exist until every fallible startup step has already succeeded, so there is no protocol channel left to explain a failure. The cause is written beside the store instead, at monet.db.startup-failure.json: the step it died in, the error and its code, the time, and the pid. The record is a sidecar of one database, named after it, so a directory holding more than one store never mixes their diagnoses. doctor prints that record on stderr before anything else, including when the store itself is too damaged to inspect.

The record holds only the most recent failure, and a later successful start does not clear it — hosts retry, so fail → fail → succeed is ordinary, and clearing on success would erase the evidence of the attempts that failed. Read the timestamp before acting on it.

Repairs are previews unless both confirmation flags are present. Choose exactly one mode:

bash
# Preview a complete rewrite to a built-in provider alias.monet repair --target hashingmonet repair --target onnx
# Exact persisted model IDs are also accepted (quote them in scripts).monet repair --target 'hashing:dim=256:tok=2' --json
# Apply only after reviewing the preview; this command never prompts.monet repair --target hashing --apply --yes
# An interrupted migration must use the sentinel's exact target.monet repair --resumemonet repair --resume --apply --yes
# Abandon is available only when core proves no vectors were rewritten and can restore the prior pin.monet repair --abandonmonet repair --abandon --apply --yes

Preview classifies the durable state before offering an apply command. An empty unpinned store or a clean, provider-compatible same-target store reports action: none; no backup or rewrite is needed, and --apply --yes refuses. Abandon preview also refuses unless a sentinel exists and core diagnostics classify it as safe. A valid target or resume preview loads and probes the exact provider but does not open the database for mutation. Apply preflights the provider again, takes exclusive SQLite ownership, and creates a verified backup before core can migrate schema or embeddings. Backups are automatic and cannot be disabled or redirected:

text
<storage-directory>/backups/monet-before-repair-<UTC>-<uuid>.db

The backup path is printed immediately and retained if later work fails. Stop other Monet processes if exclusive ownership cannot be acquired, then rerun the same command. Do not delete an active migration sentinel or edit the pin manually: use --resume, or use --abandon only when its preview says core classifies abandonment as safe. Successful previews and applies exit 0; invalid flags, provider failures, locks, unsafe abandon attempts, backup failures, and migration failures exit 1.

License

Monet is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). Full terms are in the LICENSE file included in this package. The with-monet harness is licensed separately under the Apache License 2.0.

Source: packages/cli/README.md at commit 983ff12

Tools

21

memory_store

Store durable knowledge. Similar evidence normally attaches to an existing concept; novel, incoherent, species-mismatched, or stage-mismatched evidence creates a concept. Evidence that matches several concepts equally is REFUSED rather than guessed: the error names the candidates, and you re-send with `attachTo` or `resolution="forceNew"`. The acknowledgement returns `circle`, `action`, and `conceptId`; anomalous forks also return `resolutionMode` and `score`, flagged pairs add `nearMatchId`/`nearMatchScore`, and correction/rule outcomes add `contradiction`, `ruleSuccession`, or `extractionCandidate` only when present, and a store into an archived circle adds `guidance` naming what recall will not reach. Use `attachTo` only when identity is known, or `resolution="forceNew"` for known-distinct items. Use kind="correction" to challenge prior memory. Use kind="rule" with `rule`; stored rules are advisory because blocking severity is declaration-only in memory_declare. Synthesis happens later on explicit read.

ParameterskindrulecirclecontentrequiredattachToresolutionsourceRefs

memory_declare

Declare a user-authorized rule, stage, principle, or preference, or withdraw a declared rule. Never call on agent initiative. This is the only tool that may create blocking rules, replace a rule binding, or end a declaration. A stage is a named moment; rules bind content to stages. Principles and preferences enter the always-on skeleton without stage or severity; mechanical concerns return as non-blocking `advisories`. Skeleton changes include `instruction` only when a registered standing surface became stale. A permissive standing grant is a rule, not another species. `withdraw` retires a declared rule so no stage delivers it; a rule whose deny is still live must be declared advisory first, and one carrying an open question is refused until the question is answered. memory_restore brings a withdrawn rule back.

ParametersscopestagecirclereasoncontentspeciesmodelTagseveritywithdrawdeclaredBysourceRefsexitsEvidence

memory_ratify

Record a human verdict on a principle or preference candidate after conversational review against the skeleton battery (Generates/Covers/Transfers/Exits). Approve/re-ratify enters the candidate in the skeleton and can link generated rules; reject keeps it out; retire ends current membership. The latest verdict governs membership, while every verdict remains in history. `packet` preserves exactly what the human saw. Name `entrance` so the record can later say whether anything gated this entry: "extraction" requires `battery` (all four gates answered), "declaration" forbids it because sovereignty replaced the test. Membership changes include `instruction` only when a registered standing surface became stale.

ParameterscirclepacketbatteryverdictrequiredentranceratifiedBycandidateIdrequiredmemberRuleIds

memory_overview

Read-only curation workbench for one circle: compact counts, livingModel cards, bounded queues for possibleDuplicates, extractionCandidates, openContradictions and gate exceptions, plus the ratified skeleton. A skeleton member's `homeCircle` names the circle it is homed in and appears only when that is not the circle you asked from; its absence means the member is homed here, and memory_ratify only accepts a candidate homed in the circle you pass. Opt into dirty or stale worklists; truncation fields report omissions. It never returns bodies: memory_fetch an id, use memory_resolve for contradictions or pair flags, and memory_detach with destConceptId to consolidate a duplicate. Pass entity to list one hub's memories.

ParameterscircleentityconceptLimitincludeDirtyincludeStale

memory_list

List one circle's memories as structural cards, never bodies; use memory_fetch to read one. Returns up to `limit` plus `nextCursor`; pass that as `cursor` until absent. Keyset pagination stays valid while earlier pages are reassigned. Use `withProvenance` to group memories by evidence paths, then memory_reassign_circle to migrate them.

ParameterslimitcirclecursorwithProvenance

memory_fetch

Read a concept by id. Normal concepts return `body` and `observationCount`; evidence appears only with observations:true as newest-first pages. If `needsSynthesis:true`, pull every page, reconcile one body, then call memory_synthesize. `bodyTruncated` means recover from observations. A disputed concept adds `status` and `openContradictions`; mediate with memory_resolve({ contradictionId: openContradictions[i].id }).

ParametersidrequiredcircleobservationsobservationsOffset

conformance_ask

Record that you asked the user whether an action followed the rule it read. Call this when you put the question, before their reply. The momentId is the one `stage_lookup` returned when it handed you that rule; a later `stage_lookup` also names earlier moments with no question put — candidates, not debts, because the record does not say whether an action followed any of them. Ask where one did.

ParametersmomentIdrequired

conformance_answer

Record whether the action followed the rules read at that moment: 'followed' or 'not-followed'. No question is put first — record your own reading. FIRST WRITE WINS: the same answer again is accepted, a differing one is refused, so a later correction does not land here — when a rule turns out not to have been followed, the destination is that rule's own record. This says the action followed the rule; it never says the rule caused it.

ParametersanswerrequiredmomentIdrequired

stage_lookup

At a stage named by agent_context, fetch its rules before acting. A hit returns bounded rules with reasons and omission recovery fields. `homeCircle` names the circle a rule is homed in, and appears only when that is not the circle you asked from; its absence means the rule is homed here. `parentDisputed:true` means `disputedParentIds` should be memory_fetched; projectedFromPrincipleId is only the display parent. A miss returns the live stage index.

Parametersstagerequiredcircle

memory_synthesize

Store one coherent body synthesized from all of a concept's observations. Clears `needsSynthesis` and records a revision.

Parametersidrequiredbodyrequiredcircle

memory_checkpoint

Track work and capture finds as they happen — nothing is owed at session end. When a work directive lands, open the plan: work-level items that may outlive the session (fine-grained decomposition stays in the host's own todo). When something surfaces that is not this work, `inbox` it — one line, keep moving. Before reporting completion, settle: close what resolved, and dispose the inbox with the user — do it now, `filed` with a `ref`, `dropped`, or leave open to keep. This MERGES: `open` adds, `close` resolves by id, anything unnamed stays untouched. Address a workstream by `title` (mints if new) or `id` (exact); with neither, the one this session already touched, or the only active one — several active means refusal with the list. The receipt is only what this call did: `opened`/`closed` item ids, `status` only when this call changed it, `notClosed` only when a `close` id is not in the addressed list (it did not close; an inbox item closes under `id: "inbox"`), and — only when the checkpoint landed in an archived circle — `guidance` naming that circle.

Parametersinboxcircleworkstream

memory_workstreams

Two reads, two moments. Resume — on continuation intent only, never a fresh directive: omit `id` to list active/paused workstreams and confirm which to resume; then pass its `id` for detail — OPEN items only, questions first, each carrying the id `close` takes. Settle — `id: "inbox"` before reporting completion: every find awaiting disposition, this session's and every kept one. `closedCount` says how many resolved items exist without delivering them; `includeClosed` returns them with `state`, `closedAt`, and `ref` for the filed. Advance `detailOffset` by items actually returned; `detailOmitted` is the true remainder.

ParametersidcircledetailOffsetincludeClosed

memory_flag_contradiction

Open a contradiction when stored memory conflicts with newer evidence. The concept becomes disputed until memory_resolve mediates it. Prefer memory_store kind="correction" when also storing the correcting evidence.

ParameterskindcircledetailrequiredconceptIdrequiredobservationId

memory_resolve

Mediate a contradiction or dismiss a flagged pair. CONTRADICTION: pass contradictionId, decision, and a reconciled body for accept-new/keep-current. accept-new keeps the correction; keep-current retires it; dismiss records no conflict. Name contradictedObservationId (a live, older, same-concept observation): on accept-new it is superseded exactly; on keep-current it is recorded as the kept prior while the correction is retired either way. Without it, accept-new supersedes only a sole older live observation; if several exist, none is retired and body is required. PAIR-FLAG DISMISSAL: pass conceptAId + conceptBId only. One dismissal clears both possible-duplicate and extraction-candidate flags between the pair; if only one relation is wrong, correct or detach instead. rowsUpdated:0 is an idempotent no-op.

ParametersbodycircledecisionconceptAIdconceptBIdresolvedBycontradictionIdcontradictedObservationId

memory_detach

Move observations out of a concept to undo a wrong merge. By default they form a new concept; destConceptId attaches them to an existing same-circle concept. The source is recomputed and marked for synthesis. Moving all observations into a destination deletes the source, consolidating a duplicate. Without a destination, at least one observation must remain; use memory_reassign_circle to move a whole concept across circles.

ParameterscircleconceptIdrequireddestConceptIdobservationIdsrequired

memory_reassign_circle

Move a concept, its observations, and graph membership to another circle. Pass exactly one of id or ids; batches are per-item atomic and report errors without aborting. `circle` is the current home. `auto` merges a destination match; `forceNew` keeps it distinct and flags a near match as possible_duplicate. Use this to home legacy default memory in its project circle.

ParametersididscircletoCirclerequiredresolution

memory_retire

Hide a memory: it leaves memory_search, memory_fetch, memory_list and the overview counts, its evidence untouched, and memory_restore brings it back — its graph re-derived from that evidence rather than replayed, so ordering and reinforcement history do not survive the round trip. Pass exactly one of id or ids; batches are per-item and report errors without aborting. `circle` is the concept's home. A memory leaves with the authority it entered on, so this refuses one that entered by declaration or by ratification, and one carrying an open contradiction or an undismissed duplicate/extraction pair flag — retiring those would end the question by making its subject vanish instead of answering it. Each refusal names the tool that withdraws that authority first, or says plainly when no surface does. Ordinary memories, and rules an agent stored itself, retire freely.

Parametersididscircle

memory_restore

Undo memory_retire: a retired memory is searchable, fetchable, listed and counted again, and its graph is re-derived. Pass exactly one of id or ids; batches are per-item and report errors without aborting. `circle` is the concept's home.

Parametersididscircle

memory_circle_manage

Manage project-locality circles. Rename preserves the old name as an alias. Merge moves all concepts; forceNew (default) keeps near matches distinct and flags them, while auto deduplicates. Archive hides a circle from store-wide recall/listing without deleting it; unarchive restores it. List includes archived circles. Use entities/edges, not circles, for topics.

Parameterstoactionrequiredcircleresolution

agent_context

Session-start orientation. Call first. Returns resolved `circle`; `resolvedFrom` marks an alias. `stageIndex` names moments whose rules require stage_lookup. Skeleton delivery has three states: no mirror fields means loaded standing files are current; `mirrorStale` + `instruction` requires user-confirmed reconciliation; `skeleton` contains members not covered by a standing file. A member's `homeCircle` names the circle it is homed in and appears only when that is not the circle you asked from; its absence means the member is homed here. `open` counts workstreams and inbox items still open — mention them to the user; resume only when asked.

Parameterscircle

Version history

3
  1. v1.12.0LatestNov 6, 2026
  2. v1.11.1Nov 4, 2026
  3. v1.11.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts