Noema MCP server
Commit Nov 15, 2026Provides a persistent, structured memory layer for AI agents using local markdown files and a SQLite index.
Also known as Fail-Safe/Noema
- Stars
- 25
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is Noema MCP?
Noema provides a persistent, structured memory layer for AI agents using local markdown files and a SQLite index.
Summary generated from the project's README
About Noema MCP server
Noema provides a persistent memory layer designed for AI agents to record facts, decisions, preferences, and observations. It functions as an MCP server using stdio or Streamable HTTP, making it compatible with tools like Claude Code, GitHub Copilot, Zed, Cursor, and Aider. The system operates with a local-first approach where every memory is stored as a plain markdown file, while a local SQLite database with FTS5 serves as the index for fast retrieval.
Users can manage their data through a cross-platform Rust binary available for macOS, Linux, and Windows. While core storage and lexical retrieval happen locally without requiring API keys, the server supports optional model integrations that send data to configured external endpoints. The architecture allows for peer-to-peer federation between different Cortexes using vector clocks and event logs to maintain consistency across distributed environments.
What you can do with it
- 1Store agent decisionsAn AI agent can record a specific choice and the reasoning behind it using the decision trace type.
- 2Maintain long-term contextDevelopers can use the system to give agents a structured place to record situational background information.
- 3Sync memory across editorsA developer can edit markdown files in Obsidian or VS Code and have those changes automatically reflected in the agent's memory.
- 4Search historical knowledgeYou can perform full-text searches across all recorded traces to find specific information.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
NOEMA_DURABILITY
| Name | Description | |
|---|---|---|
| NOEMA_DURABILITY | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefail-safe/noema is public and reachablegithub.com/fail-safe/noema ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/fail-safe/noema ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- 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 GitHubThe intentional memory layer for your AI agents.
Noema gives AI agents — and the humans working alongside them — a persistent, structured place to record what they know, decide, observe, and intend. Every memory is a plain markdown file. The index is a local SQLite database. Core storage and lexical retrieval run locally without an API key. Optional model integrations process data at their configured endpoints; choosing an external endpoint sends that integration's inputs to the external service.
In short:
- Local-first agent memory exposed as an MCP server (stdio + Streamable HTTP). Works out of the box with Claude Code, GitHub Copilot, Zed, Cursor, Aider, and anything else that speaks MCP.
- Plain markdown on disk as the source of truth; a local SQLite database with FTS5 as the index. Core memory storage requires no cloud service or API key.
- One cross-platform Rust binary with SQLite and the Hermes and Obsidian plugin installers built in. Release archives cover macOS, Linux, and Windows on x86-64 and ARM64.
- Peer-to-peer federation across Cortexes with vector clocks, event-log audit trail, and
divergencetraces on concurrent edits. - Your editor is a first-class client. A filesystem watcher turns Obsidian / VS Code / Finder / iCloud edits into real mutation events — same events as MCP-initiated writes, propagated through federation.
- Standards-friendly. Ships an auto-generated
AGENTS.mdper Cortex, a native Hermes memory-provider plugin, and SHA-256 content hashing with optional source-locking for publishers.
Concepts
| Term | Meaning |
|---|---|
| Trace | A single memory — one markdown file + its database row |
| Cortex | A named collection of Traces, stored in a directory you control |
Contributor and architecture notes:
- Repository Guidelines
- Architecture
- Trace citations —
noema:{id}chat/copy form and flexible tag list inputs - Development Guide
- Cross-agent continuity evaluation — Codex/OpenCode benchmark evidence
- Decision-assisted retrieval — current testing scope and data-processing boundaries
- Trace citations —
noema:{id}chat/copy form without renaming durable IDs - Why Noema switched to Rust — benchmarked cutover rationale
A Trace has a type that describes its intent:
| Type | Meaning |
|---|---|
fact |
A discrete thing that is true |
decision |
A choice made and why |
preference |
A behavioral or stylistic lean |
context |
Situational background |
skill |
A learned capability or procedure |
intent |
Something that needs to happen |
observation |
Something witnessed but not yet verified |
note |
Anything else |
divergence |
A concurrent edit conflict, auto-created by federation sync |
Installation
With Homebrew (macOS + Linux)
The fastest path. One command taps Fail-Safe/homebrew-tap and
installs the cross-platform formula covering darwin/{amd64,arm64}
and linux/{amd64,arm64}:
brew install Fail-Safe/tap/noema
On macOS a cask is also published for users who prefer the cask ecosystem:
brew install --cask Fail-Safe/tap/noema
The formula path is the default on macOS — when a tap contains both a formula and a cask of the same name,
brew install(without--cask) resolves the formula first. Pass--caskto opt into the cask. Linux users get the formula automatically.
Prefer the two-step form? It works the same:
brew tap Fail-Safe/tap
brew install noema # formula (macOS + Linux)
brew install --cask noema # cask (macOS only)
Beta channel
Prerelease builds (v*-beta*, v*-rc*, v*-alpha*) publish to a
parallel formula so you can track the edge without the stable channel
moving under you:
brew install Fail-Safe/tap/noema-beta
noema-beta installs the same noema binary and conflicts with the
stable formula — Homebrew will refuse to install both at once. To
switch channels:
brew uninstall noema # (or noema-beta)
brew install Fail-Safe/tap/noema-beta # (or noema)
brew upgrade on noema-beta pulls the newest prerelease; stable tags
(v0.21.0 vs v0.21.0-rc.1) stay on their respective channels.
Download a pre-built binary
Grab the archive for your OS/arch from the
Releases page, verify it
against checksums.txt, and put noema somewhere on your $PATH:
# macOS (Apple Silicon) — adjust VERSION, OS, and ARCH as needed.
VERSION=0.21.3
OS=darwin
ARCH=arm64
ARCHIVE=noema_${VERSION}_${OS}_${ARCH}.tar.gz
curl -LO https://github.com/Fail-Safe/Noema/releases/download/v${VERSION}/${ARCHIVE}
curl -LO https://github.com/Fail-Safe/Noema/releases/download/v${VERSION}/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf "${ARCHIVE}"
sudo mv noema /usr/local/bin/
noema version
Release archives bundle SQLite, so there is no separate database library to
install. Supported targets:
darwin/amd64, darwin/arm64, linux/amd64, linux/arm64,
windows/amd64, windows/arm64.
Build from source
Building requires Rust 1.88 or newer:
git clone https://github.com/Fail-Safe/Noema.git
cd Noema
make build # dev build with debug info -> ./noema
make release # stripped build for this host -> dist/noema-<os>-<arch>
make test # format, lint, and full Rust suite
Development builds retain line tables while omitting dependency debug symbols
to keep Cargo artifacts manageable. Release builds enable thin LTO, use one
codegen unit, and strip symbols. make help lists all targets.
Pre-1.0 notice. Noema is currently on the
v0.xline. Expect breaking changes between minor releases until v1.0. Cortex data on disk is forward-compatible via non-destructive migrations; anycortex.mdversion bump that requires a manual step ships with an explicitnoema migratecommand.
Quick Start
Set up with your AI agent
After installing Noema, tell your agent:
Run
noema instructions quick-startand help me follow it. Inspect existing setup first, ask before changing configuration, and verify memory access through this agent's actual MCP connection.
noema instructions prints an overview; noema instructions quick-start covers
shell completions, your first Cortex, and MCP integration. Federation is optional:
use noema instructions federation when you want separate Cortexes to exchange
memories. These commands only print guides embedded in the installed binary;
they work before a Cortex or configuration exists and never perform setup changes.
The same guides are readable in docs/instructions.
Manual quick start
# Create a Cortex
noema init --name my-cortex
# Add a Trace interactively
noema add
# Add a Trace with flags
noema add --title "We chose local SQLite" --type decision --tag storage --body "Markdown remains the source of truth."
# List Traces
noema list
# Search
noema search "sqlite"
# Render bounded prompt-relevant context without a model tool call
printf '%s' "What did we decide about storage?" | noema prefetch
# View a Trace
noema get 20260329-we-chose-local-sqlite
noema initalso writes anAGENTS.mdat the cortex root — the agents.md convention that Codex, Cursor, Aider, Zed, Copilot, and most other coding-agent tooling pick up automatically. Any agent pointed at the directory will find a complete reference for the Trace format and the MCP tools without any additional onboarding.
CLI Reference
noema init --name <name> [--path <dir>] Create a new Cortex
noema instructions Print the agent setup overview (read-only)
noema instructions quick-start Print the shell, Cortex, and MCP setup guide
noema instructions federation Print the optional federation setup guide
noema use <name> Set the default Cortex
noema cortex list List all known Cortexes
noema cortex storage <name> [--json] Inspect database, WAL, and reusable-space statistics
noema cortex storage <name> --database <default|nosync> --backup <path>
Safely change database storage with a backup
noema cortex storage <name> --resume Finish an interrupted storage migration
noema cortex compact <name> --backup <path> [--json]
Compact a stopped database with backup and integrity checks
noema cortex remove <name> [--purge] [--force]
Unregister a Cortex (--purge also deletes its directory)
noema cortex backup <name> [-o <path>] [--force]
Write a gzipped tarball of a Cortex
noema cortex restore <tarball> [--name <n>] [--path <dir>] [--force]
Restore a Cortex from a backup tarball
noema cortex recovery-status <name> Inspect interrupted mutation recovery without changing the Cortex
noema cortex restore-status List durable restore transactions without exposing sensitive paths
noema cortex restore-recover <transaction-id> --action <resume|rollback>
Resume or roll back an interrupted Cortex restore
noema add [flags] Add a Trace (interactive if flags omitted)
noema list [flags] List Traces
noema get <id> Show a Trace
noema edit <id> Edit a Trace in $EDITOR
noema append <id> [--content <text>] Append to a Trace body (pipe-friendly: `echo X | noema append <id>`)
noema remove <id> [--force] Move a Trace to recoverable trash
(--force only overrides source-lock protection)
noema recover <id> [--force] Restore a Trace from trash
(--force overrides source-lock protection)
noema purge [--days N] Permanently delete all trashed Traces older than N days
noema search <query> [flags] Full-text search (FTS5). --semantic / --hybrid
rank by embedding similarity (needs a search: block + backfill)
noema prefetch [flags] Read a prompt from stdin and emit confidence-gated relevant context
(`--input codex-hook --output codex-hook` for Codex hooks)
noema similar <id> [--limit N] Find traces related to <id> (BM25; --semantic / --hybrid for embeddings)
noema embeddings status Show semantic-search embedding coverage (embedded / stale / missing)
noema embeddings backfill [--force] [--limit N]
Embed traces that are missing or stale (for semantic search)
noema plugin list List plugins embedded in this binary
noema plugin status [--check] [--hermes-home PATH] [--vault PATH]
Check installed plugins for drift
noema plugin hermes status [--check] [--hermes-home PATH]
noema plugin hermes install [--check] [--force] [--hermes-home PATH]
Inspect or install the embedded Hermes runtime files
noema plugin obsidian status [--check] --vault PATH
noema plugin obsidian install [--check] [--force] --vault PATH
Inspect or install the embedded Obsidian runtime files
noema integrate list List supported agent-client adapters
noema integrate status [CLIENT] [--scope user|project] [--check]
Inspect installed MCP and startup-bootstrap state
noema integrate CLIENT install --scope user|project [--check] [--force]
Install a local stdio integration
noema integrate CLIENT install --scope user|project --transport http --url URL
[--bearer-token-env ENV] [--check] [--force]
Install an HTTP integration using an environment reference
noema integrate CLIENT remove --scope user|project [--check] [--force]
Remove only recognized Noema integration components
noema integrate CLIENT print --scope user|project [connection flags]
Print generated fragments without changing files
noema archive <id> Archive a Trace
noema unarchive <id> Restore an archived Trace
noema sync [--recover] Re-index trace files; --recover rebuilds missing files from the event log
noema events [trace-id] [--since] [--limit]
Show the event log (audit trail) for a trace, or recent events across all traces
noema events backfill [--dry-run] [--yes]
Synthesize create events for active traces missing one (e.g. traces added via `noema sync`)
noema resolve <divergence-id> --accept <origin> | --custom <body>
Resolve a divergence (concurrent edit conflict)
noema verify [--backfill] Run integrity checks (alias for `verify traces` for back-compat);
--backfill populates content_hash for old traces
noema verify traces [--backfill] Check trace content hashes against frontmatter content_hash
noema verify cortex Validate manifest, config, db, access posture, and federation
noema verify drift Check federated traces for drift from their source hash
noema memory stats [--detailed] Show tier counts and (with --detailed) engagement signal
noema memory health [--since 24h] Show consolidation activity over the window, promotion-latency
percentiles, and the 1-source mid leak detector
noema memory popular [--top 10] Top traces by search popularity and top tags by aggregate engagement
noema memory promote <id> [--to mid|long] Advance a trace one tier (short→mid or mid→long)
noema memory demote <id> Step a mid trace back to short
noema memory purge <id> --tier <t> --reason "..." --confirm [--hard]
Ceremoniously destroy a trace with audit trail (GDPR path)
noema metrics summary [--since 7d] Compact local MCP/CLI op latency and volume summary
noema metrics report [--since 24h] Full local op metrics (p50/p95, daily volume, modes)
noema metrics prune [--days 30] --yes Delete local op metric rows older than the retention window
noema consolidate [flags] Run an LLM-backed consolidation pass
noema migrate cortex-id [--reset] [--yes] Assign or deliberately replace a Cortex federation identity
noema tags stats [--limit 50] [--output text|json]
Show cortex-wide tag, visibility, tier, and engagement counts
noema tags rename <old> <new> [-i] [--dry-run] [-y]
Rename a tag across active and archived traces
noema tags delete <tag> [-i] [--dry-run] [-y]
Remove a tag across active and archived traces
noema tags doctor [--fix] [-y] [--output text|json]
Diagnose tag hygiene and optionally apply deterministic fixes
noema federation status Show federation config, MCP access posture, peer sync state, and vector clock
noema federation peers List configured federation peers
noema federation add-peer <name> <endpoint>
Add a federation peer to cortex.md
noema federation reset-peer <name>... Clear stored state for a peer (forces a fresh handshake; use after a peer
ran `noema migrate cortex-id --reset` and the syncer is now reporting an
identity mismatch)
noema federation set-mode <sync|publish|subscribe>
Set the cortex-level federation mode
noema federation pause-peer <name> Pause syncing with a peer (preserves cursor + identity)
noema federation resume-peer <name> Resume syncing with a paused peer
noema federation key fingerprint Print the SHA-256 fingerprint of the active MCP shared key (safe to
say aloud over an out-of-band channel to confirm a pairing)
noema keygen [--force] Generate this cortex's Ed25519 federation signing key so it can sign
the events it emits (--force rotates it; peers must re-pin)
noema serve [--transport stdio|http] [--host <addr>] [--host-dynamic <addr>] [--allowed-host <name>] [--tls-cert <file> --tls-key <file>]
Start the MCP server (http requires --host; endpoint is /mcp)
noema serve --print-config Print a ready-to-use .mcp.json snippet and exit
noema serve ... --print-systemd-unit Print a systemd service unit for the current serve flags
noema serve ... --print-launchd-plist Print a launchd LaunchAgent plist for the current serve flags
noema tui [--theme auto|dark|light] Open the interactive TUI
noema config get <key> Print a user-level setting (ui.theme, trash_days)
noema config set <key> <value> Update and persist a user-level setting
noema config list List every known config key with its current value
noema completion [bash|zsh|fish|install] Generate shell completions
noema version Print version, commit, and build date
TUI theme priority (highest wins):
--themeflag onnoema tuiNOEMA_THEMEenvironment variableui.themein~/.config/noema/config.yaml(noema config set ui.theme dark)auto— detected from the terminal's reported background color
Common flags:
--cortex <name> Target a specific Cortex (overrides NOEMA_CORTEX env and config default)
--type <type> Filter by Trace type
--author <name> Filter by author
--tag <tag> Filter by tag
--archived Show only archived Traces
--trashed Show only trashed Traces
--all Show active and archived Traces
Cortex selection priority (highest wins):
--cortexflagNOEMA_CORTEXenvironment variable- Default set via
noema use <name>
Database storage in iCloud Drive
Use opt-in nosync storage to keep the database and its SQLite sidecar files in
db.nosync/ while Markdown traces continue syncing. The storage command creates
a backup and safely moves an existing database. See
database storage for enabling, reversing, recovering,
and backing up this layout, including iCloud's parent-folder eviction limits.
Database maintenance
noema cortex storage <name> reports database size, reusable free space, WAL size,
and compaction headroom. Add --json for structured output. For deliberate
compaction, stop clients and use noema cortex compact <name> --backup <archive>.
Noema requires a complete external backup and verifies database integrity before
and after compaction. See database maintenance.
Durability profiles
Noema defaults to the standard durability profile. It matches the mutation
and crash posture of the former Go implementation while retaining Rust's
performance and memory improvements. No environment variable is required.
Set NOEMA_DURABILITY=strong for processes that need Noema's opt-in recovery
journal, stable mutation locks, atomic temporary-file replacement, and explicit
flushes:
NOEMA_DURABILITY=strong noema serve --transport stdio
strong materially reduces write throughput in exchange for recovery guarantees
that were not available in the Go implementation. It has passed Noema's
process-death and macOS APFS detach/remount recovery tests; hard power-cut and
device-cache-loss qualification remains outside that claim. Unknown profile
names fail closed, and MCP runtime introspection reports the active profile as
cortex_usage.runtime.durability_profile. See
Why Noema switched to Rust
for measurements and the full trade-off.
Agent Integrations
MCP read-only hints describe the purpose of a tool. Retrieval tools such as
get_trace, search_traces, recall_context, and find_similar_traces advertise
readOnlyHint: true while retaining Noema's built-in access and search-hit
tracking. These signals help Noema assess memory importance and are part of
retrieval, not a separate operation agents must remember to perform. The existing
record_usage argument controls explicit read counts; it does not change the
read hint or disable automatic search-hit tracking. Read hints do not promise
zero database writes: internal metrics and metrics retention also continue.
Tools that can explicitly change trace content, tags, or lifecycle remain writes.
noema integrate connects a Cortex to supported coding agents and installs a
small startup bootstrap for memory retrieval and preference-revision reuse. An
MCP entry without that bootstrap is callable but not reliably memory-aware after
a fresh session or compaction.
Supported clients are codex, claude-code, cursor, opencode (OpenCode v1),
and ohmypi (Oh My Pi / OMP). Pi is listed as planned because it needs a
first-class MCP extension rather than configuration alone; OMP has native MCP
support.
Noema MCP questions
Does Noema require an API key?
No, core memory storage and lexical retrieval run locally without an API key.
What format are the memories stored in?
Every memory is stored as a plain markdown file on disk.
Which AI agents are compatible with Noema?
It works with Claude Code, GitHub Copilot, Zed, Cursor, Aider, and any other client that supports the Model Context Protocol.
How is the memory indexed?
The index is a local SQLite database using FTS5.