Noema智能记忆层

Installation

Build from source

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 release-linux        # stripped build for linux/amd64 -> dist/noema-linux-amd64

Dev builds keep the symbol table and DWARF info for debugging (~19 MB). Release builds strip both and run with -trimpath for a ~13 MB static binary with the git version embedded via -ldflags. make help lists all targets.

Pre-1.0 notice. Noema is currently on the v0.x line. Expect breaking changes between minor releases until v1.0. Cortex data on disk is forward-compatible via non-destructive migrations; any cortex.md version bump that requires a manual step ships with an explicit noema migrate command.

---

Quick Start

```bash

Claude Desktop — merge the "noema" block into ~/Library/Application Support/Claude/claude_desktop_config.json

noema serve --print-config ```

The --cortex flag, NOEMA_CORTEX env, and config default are all respected, so --print-config always reflects the cortex you would actually use.

Log destination. In stdio mode, operational logs (watcher events, federation sync status, startup messages) are written to $XDG_STATE_HOME/noema/<cortex>.log — defaulting to ~/.local/state/noema/<cortex>.log — so MCP clients that inherit the spawning terminal's stderr (Claude Code, Copilot, Zed, Cursor, Aider, etc.) don't dump logs into your active terminal. The single [serve] logs -> <path> line printed at startup tells you exactly where to tail -f. Override the destination with --log-file <path>, or force logs back to stderr with --log-stderr for interactive triage.

Semantic search (optional)

Lexical FTS5 search is always on. An opt-in semantic layer adds embedding-based ranking — useful when a query matches by concept rather than shared words (e.g. "how do we authenticate agents" surfacing a trace titled "bearer-key posture for the MCP endpoint"). It stays true to Noema's lightweight, local-first posture: embeddings are stored as a SQLite BLOB and cosine similarity is computed in pure Go — no CGo, no vector extension, no external vector database. Embeddings are a local index (never federated), like the FTS5 index.

Enable it with a search: block in cortex.md:

search:
  semantic_enabled: true
  embedding_model: nomic-embed-text          # required — no default
  embedding_endpoint: http://localhost:11434/v1   # OpenAI-compatible /embeddings;
                                             # inherits consolidation.local_llm_endpoint if unset
  # default_mode: hybrid    # lexical | semantic | hybrid (default lexical)
  # hybrid_weight: 0.5      # vector weight in hybrid fusion (0..1)
  # max_chars: 32000        # per-trace embed-text budget; lower for small-context models

Then build the index and search:

noema embeddings backfill            # embed existing traces (idempotent)
noema embeddings status              # coverage: embedded / stale / missing
noema search "concept query" --semantic
noema search "concept query" --hybrid   # fuse FTS5 + embeddings (reciprocal rank fusion)
noema similar <id> --semantic

Over MCP, search_traces and find_similar_traces take a mode arg (lexical | semantic | hybrid). If semantic search isn't configured or the embedding endpoint is unreachable, both degrade to lexical results with a note rather than erroring. Under noema serve, a background maintainer re-embeds new and edited traces on an interval, so the index stays fresh without a manual backfill.

---

Configure peers in `cortex.md`

```markdown

--- name: alpha purpose: Primary research cortex owner: mark created: 2026-03-29 version: 2 federation: interval: 30s peers: - name: beta endpoint: http://192.168.1.10:3000 - name: gamma endpoint: https://192.168.1.11:3000

ca: /etc/noema/beta-ca.pem # optional, for self-signed TLS

Or add a peer from the CLI:

Configure

hermes memory setup # select "noema", provide your cortex name ```

The plugin exposes six tools to the agent (noema_search, noema_remember, noema_recall, noema_list, noema_update, noema_lineage), manages a session log trace across turns, creates a summary trace at session end, and mirrors Hermes built-in memory writes as Noema traces.

By default the plugin spawns noema serve --transport stdio as a subprocess — no network config needed. For remote cortexes or multi-agent setups, set transport=http to connect to an already-running HTTP endpoint.

See plugins/hermes/README.md for full configuration and usage details.

---

CLI Reference

noema init --name <name> [--path <dir>]   Create a new Cortex
noema use <name>                          Set the default Cortex
noema cortex list                         List all known Cortexes
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 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>                         Move a Trace to trash (--force to hard-delete)
noema recover <id>                        Restore a Trace from trash
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 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 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 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 serve [--transport stdio|http] [--host <addr>] [--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):

1. --theme flag on noema tui
2. NOEMA_THEME environment variable
3. ui.theme in ~/.config/noema/config.yaml (noema config set ui.theme dark)
4. 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):

1. --cortex flag
2. NOEMA_CORTEX environment variable
3. Default set via noema use <name>

---

Hermes Integration

Noema ships a Hermes memory provider plugin in plugins/hermes/. It implements the Hermes MemoryProvider ABC so any Hermes agent can use a Noema Cortex as its memory backend — structured traces with types, tags, lineage, and full-text search, all through the standard Hermes lifecycle hooks.

Quick setup:

```bash

Download the plugin from the latest release

curl -LO https://github.com/Fail-Safe/Noema/releases/latest/download/noema-hermes-plugin.tar.gz mkdir -p <hermes-install>/plugins/memory/noema tar -xzf noema-hermes-plugin.tar.gz -C <hermes-install>/plugins/memory/noema/