Noema — the 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, indexed by a local SQLite database, exposed to agents through an MCP (Model Context Protocol) server. Nothing lives in the cloud; nothing requires a paid cloud API key.

Why Noema?

• Federated by design. Multiple Cortexes can pair into a ring and sync peer-to-peer. Publishers can broadcast read-only knowledge; subscribers can consume without polluting upstream. Grow a shared memory across a team, a lab, or a research network — no central server, no gatekeeper.
• Local-first. No cloud, no API keys, no account required. Your memories live in ~/.noema/.
• Plain markdown. Every Trace is a file. You can cat, grep, and git commit it — no proprietary format.
• Your editor is a first-class client. Edit Traces in an editor of your choice, be it Obsidian, VS Code, vim, or something else altogether. Drop new markdown files into traces/ from Finder. Delete, rename, or drag between folders. A background watcher sees every change and emits a proper sync event — so your manual edits propagate through federation exactly like MCP-initiated ones, and deletes are recoverable from the event log.
• MCP-native. Works with Claude Code, Copilot, Zed, and any MCP-compatible agent out of the box. Ships a native Hermes memory provider plugin — any Hermes agent can use a Cortex as its memory backend.
• Plays well with the agent ecosystem. Every Cortex ships with an auto-generated AGENTS.md — the community-standard agent-instructions format picked up by Codex, Cursor, Aider, Zed, Copilot, and most other coding-agent tooling. Any agent dropped into the directory knows how to work with it, no custom onboarding required.
• Integrity built in. Every Trace is content-hashed on write. Publishers can source-lock authoritative traces so consumers can't accidentally edit them. noema verify catches tampering; noema drift catches divergence from the source.
• Security from day one. Keyed MCP auth that refuses to serve bearer keys over plaintext, explicit host-binding rules, and out-of-band key verification — the security work most projects defer to v2 is in v1.

Concepts

Every Trace has a type that describes its intent — fact, decision, preference, context, skill, intent, observation, or note.

Federation

Two or more Cortexes can pair into a ring and sync peer-to-peer. Every Trace, every lineage edge, every audit event replicates across every peer — no central server, no cloud broker.

When two peers edit the same Trace concurrently, Noema refuses to overwrite either side. Instead it creates a divergence Trace that preserves both versions verbatim, so you can resolve it deliberately when you're ready. Nothing is ever lost; nothing is ever silently decided for you.

Federation supports three modes: sync for collaborative rings, publish for read-only knowledge broadcast, and subscribe for consumption without upstream pollution. Source-locked traces from a publisher are enforced as immutable on the consumer side — the content can't be edited, only archived or resolved through the publisher.

A personal cortex becomes a lab cortex becomes a research-network cortex. Memory grows with the collective, on your terms.

Security

A federated ring of memories is worth defending. Noema's HTTP MCP endpoint supports a keyed mode where every request must carry a bearer key — and when keyed mode is active, the server refuses to start without TLS. A bearer token over plaintext is worse than no auth at all; Noema treats that combination as a hard startup error, not a warning.

Rings share one key, verifiable via a fingerprint command so every peer knows it's talking to the right ring. Keys live in environment variables or 0600 sidecar files, never in command-line history.

The HTTP transport demands an explicit host — binding to 0.0.0.0 is rejected outright, so a federation peer can't be accidentally exposed to every interface on the machine. The cortex must be named explicitly too; no silent defaults on a network-facing endpoint.

The work many projects push to v2 — auth middleware, host-binding safety, fingerprint verification, divergence-aware conflict resolution — is in v1.

Frequently asked

Get started

Install with Homebrew (macOS + Linux):

brew install Fail-Safe/tap/noema

Then create a Cortex and start the MCP server:

$ noema init --name my-cortex
$ noema serve --transport stdio

Prefer a pre-built binary, the Go toolchain, or building from source? See the README — Installation.

Set up via an AI agent

Prefer to have your coding agent do the install for you? Copy the block below and paste it into Claude Code, Cursor, Copilot, Zed, Aider, or any other MCP-capable agent. If you're an LLM reading this page directly, follow the same steps yourself.

Please install Noema as my agent memory backend and configure it for this session.

1. Install the `noema` binary. On macOS/Linux prefer Homebrew (`brew install Fail-Safe/tap/noema`); otherwise use the Go toolchain (`go install github.com/Fail-Safe/Noema/cmd/noema@latest`).

2. Create a Cortex. Pick a short descriptive name based on this project (e.g. "my-project-memory"). Don't include a date in the name; `noema init` prepends today's date automatically.

    noema init --name <cortex-name>

3. Generate an MCP server configuration snippet and install it into this agent host's MCP config.

    noema serve --cortex <cortex-name> --print-config --transport stdio

   Merge the `mcpServers.noema` entry from the output into the correct file for the host — Claude Code: `~/.claude.json` or the workspace's `.mcp.json`. Cursor / Zed / GitHub Copilot: that host's MCP servers setting. Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS.

4. Reload or restart the agent host so the new MCP server is registered, then call the `get_instructions` MCP tool to verify the connection. That tool returns the Noema agent reference — trace types, frontmatter fields, filtering options, and the full MCP tool list — which you should read before creating traces.

5. When creating traces, always assign a `type` that reflects intent: `fact`, `decision`, `preference`, `context`, `skill`, `intent`, `observation`, or `note`. This is load-bearing for future retrieval and lineage.

Reference: https://noemacortex.com/llms.txt
Source:    https://github.com/Fail-Safe/Noema

Already have noema installed? Skip to step 3 — noema serve --print-config prints a ready-to-paste MCP entry for your host's config file.