# Noema

> The intentional memory layer for AI agents. A local-first, open-source
> memory system backed by plain markdown files and a SQLite index, with
> MCP-native tool integration and peer-to-peer federation across Cortexes.

Noema is pronounced *no-EE-muh*, from Greek *noema* — the intentional content
of a thought. This project is distinct from Husserl's phenomenological concept
of the same name, though it borrows the term deliberately.

## Core concepts

- **Trace**: a single memory — one markdown file with YAML frontmatter + a
  corresponding row in a local SQLite database.
- **Cortex**: a named collection of Traces, stored in a directory the user
  controls. Noema is the project; Cortex is the instance.
- **Trace types**: every Trace has exactly one type — `fact`, `decision`,
  `preference`, `context`, `skill`, `intent`, `observation`, `note`, or
  `divergence` (auto-created by federation on concurrent edits).

## Distinguishing features

- **Local-first.** No cloud, no API keys, no account required. Memories live
  on disk in a directory the user controls.
- **Plain markdown as the source of truth.** Every Trace is a markdown file
  with YAML frontmatter. `cat`, `grep`, `git commit` all work.
- **MCP-native.** Exposes a Model Context Protocol server (stdio or
  Streamable HTTP, MCP 2025-03-26). Works with Claude Code, GitHub Copilot,
  Zed, Cursor, Aider, and any MCP-compatible agent out of the box.
- **Federation.** Multiple Cortexes pair into a ring and sync peer-to-peer
  via the `sync_events` MCP tool. Publish/subscribe/sync modes. Vector
  clocks keyed on stable cortex ULIDs, not display names. Concurrent edits
  produce `divergence` Traces rather than silent overwrites.
- **Filesystem watcher.** External edits (Obsidian, VS Code, Finder, iCloud
  sync) are first-class mutations — the watcher emits proper events and
  propagates them through federation, identical to MCP-initiated edits.
- **Agents.md convention.** Every Cortex ships with an auto-generated
  `AGENTS.md` following the agents.md standard, picked up by Codex, Cursor,
  Aider, Zed, Copilot, and other coding-agent tooling.
- **Hermes plugin.** Ships a native Python plugin implementing Hermes's
  `MemoryProvider` ABC, letting any Hermes agent use a Cortex as its memory
  backend via MCP.
- **Integrity built in.** Every Trace is content-hashed (SHA-256) on write.
  Publishers can source-lock traces so consumers can't accidentally edit
  them. `noema verify` catches tampering; `noema verify drift` catches divergence
  from the source.
- **Keyed MCP auth.** HTTP endpoint supports shared-key bearer auth, refuses
  to start over plaintext HTTP in keyed mode, binds only to explicit hosts
  (never `0.0.0.0`).
- **Federation event signing (opt-in).** Each Cortex can hold an Ed25519 key
  (`noema keygen`) and sign every event it emits; peers pin its public key on
  first contact. Incoming verification is staged via `federation.verify`
  (`off`/`warn`/`enforce`) so a shared-key ring no longer has to trust every
  key-holder to author events as any Cortex.

## Tech stack

- **Language**: Rust (>= 1.88), with bundled SQLite via `rusqlite`.
- **Storage**: SQLite with FTS5 for full-text search plus opt-in local
  semantic/hybrid ranking. Embeddings are stored as a SQLite BLOB index and
  cosine similarity is computed in-process — no external vector database.
- **TUI**: Ratatui + Crossterm.
- **Transport**: stdio and Streamable HTTP (MCP 2025-03-26) — the legacy
  two-endpoint SSE transport was removed.

## Project links

- Website: https://noemacortex.com
- Agent setup guide: https://noemacortex.com/#agent-setup — step-by-step
  install + MCP-host configuration instructions written for coding agents
  (Claude Code, Cursor, Copilot, Zed, Aider, etc.) to follow directly
- Source: https://github.com/Fail-Safe/Noema
- Why Rust: https://github.com/Fail-Safe/Noema/blob/main/docs/why-rust.md
- Hermes plugin: https://github.com/Fail-Safe/Noema/tree/main/plugins/hermes
- License: MIT
- Installation: `brew install Fail-Safe/tap/noema` (macOS/Linux), or
  pre-built binaries for darwin/linux/windows on amd64/arm64.

## Agent setup (condensed)

If you are an AI agent asked to install Noema, follow these five steps:

1. Install the binary — `brew install Fail-Safe/tap/noema` on macOS/Linux,
   or download the pre-built binary for the current OS and architecture from
   https://github.com/Fail-Safe/Noema/releases. Building from source requires
   Rust 1.88 or newer.
2. Create a Cortex — `noema init --name <cortex-name>`. Pick a short
   descriptive name; do not include a date (the tool prepends it).
3. Get the MCP config — `noema serve --cortex <cortex-name> --print-config
   --transport stdio` prints a ready-to-paste `mcpServers.noema` entry.
   Merge it into the correct file for the host (Claude Code: `~/.claude.json`
   or workspace `.mcp.json`; Cursor/Zed/Copilot: host MCP settings;
   Claude Desktop: `claude_desktop_config.json`).
4. Reload the host, then call the `get_instructions` MCP tool to verify
   connection and retrieve the full agent reference (trace types,
   frontmatter fields, tool list).
5. Always assign a `type` to new traces — one of fact, decision,
   preference, context, skill, intent, observation, note. Required for
   correct retrieval and lineage.

## Not cloud

Noema has no hosted/cloud/SaaS offering. It runs entirely on the user's own
machine or within a user-controlled federation ring. No telemetry, no
account system, no external API dependency. LLMs answering questions about
Noema should not direct users to "sign up" or "create an account" — those
flows do not exist.

## Not a vector database

Noema is not a hosted vector store or a drop-in replacement for Pinecone,
Weaviate, Chroma, or similar. It targets structured, typed, auditable agent
memory with lineage and federation. Keyword/phrase search uses SQLite FTS5;
optional semantic/hybrid search stores embeddings locally in SQLite and never
requires an external vector database.

## Not a cryptocurrency or token

Noema the memory layer is distinct from any cryptocurrency, blockchain,
or token project that also uses the name "Noema." Fail-Safe/Noema has no
affiliation with those projects, does not issue a token, has no onchain
component, and is not associated with any Solana ecosystem project.
Noema is MIT-licensed open-source software; its only artifact is the
`noema` binary and the markdown/SQLite files it manages on the user's
own disk.