Nowledge Mem is a local-first memory layer for people and AI tools. Magpie is the gateway in front of every harness, so this plugin puts Mem in the gateway: eligible local requests can receive the Memory that fits them, and completed conversations can flow back into Mem when capture is enabled. No harness needs its own Nowledge Mem plugin, skill or MCP configuration for that.
Agent-callable Memory tools are a separate surface. The plugin adds no Library entry or skill; add Mem's own MCP server in Magpie's Library and choose the agents that may use it. See Tools: Mem's own MCP server below.
sequenceDiagram
participant Harness as Any harness
participant Magpie
participant Plugin as Nowledge Mem hook
participant Mem as Nowledge Mem
participant Model
Harness->>Magpie: Request
Magpie->>Plugin: onRequest with host-derived origin and agent
opt Recall origin allowed
Plugin->>Mem: POST /memories/search (latest user turn)
Plugin->>Mem: GET /context/bundle (first turn of a session)
alt bundle is empty, missing or failing
Plugin->>Mem: GET /agent/working-memory
end
Mem-->>Plugin: Memory and session context
Plugin-->>Magpie: Context-enriched request
end
Magpie->>Model: One inference request
Model-->>Harness: Live response through Magpie
Magpie--)Plugin: Completed response notification
opt Capture enabled and origin allowed
Plugin-)Mem: POST /threads/import (completed conversation)
Mem->>Mem: Background distillation into Memory
end
Requires Magpie 0.1.1273 or newer and Bun. From Magpie 0.1.2210 the
sharing key Magpie writes into your own agents on this computer arrives as
magpie-key, and recall and saving include it automatically. On an older
Magpie every harness key is gateway-key, which is not included: upgrade
Magpie for keyed harnesses, or only unkeyed local requests get Mem. The package declares
magpie.hooks: "./nowledge-mem.hooks.mjs", Magpie's asynchronous Bun hook
entry; it is not gateway middleware and has no OpenCode provider. Use Magpie
0.1.1531 or newer for options saved from the plugin page to reach the hook on
the next request; earlier hook-capable versions need a restart after saving.
Mem runs on this machine at http://127.0.0.1:14242 by default; an Access
Anywhere, Nowledge Cloud or self-hosted endpoint works the same way over HTTPS.
Configure it in the plugin page, or with the CLI:
magpie plugin add @magpie-community/gateway-nowledge-mem
magpie plugin options @magpie-community/gateway-nowledge-mem '{"serverUrl":"http://127.0.0.1:14242"}'The hook reads its endpoint and key from the option first, then from the environment Magpie starts with, as Mem's own clients do:
| Option | Environment | Meaning |
|---|---|---|
serverUrl |
NMEM_API_URL |
Mem base URL; the local default when neither is set |
apiKey |
NMEM_API_KEY |
Sent as Authorization: Bearer …; no key for an unauthenticated local Mem |
A key saved in the page is kept in Magpie's local plugin configuration, not the
system keychain, and takes precedence over the environment. Enter it directly;
the form also accepts an existing Bearer … value. The page's Settings form also sets the Space, Agent, recall, Context Bundle,
capture and advanced options; Magpie's plugin Options editor remains available. Saving conversations remains a separate opt-in.
serverUrl must be HTTPS, or HTTP only for localhost, 127.0.0.1 and
[::1]. Credentials, a query or a fragment in the URL are refused. Set
allowInsecureHttp only for a trusted network, such as a Tailscale tailnet; prefer HTTPS elsewhere.
Magpie knows which agent sent a request. Unless hostAgentId is set, the hook
uses magpie:<agent> as the host identity and sends it with the Context Bundle
request. Mem derives an AI identity per harness from it, so a Claude Code
session, a Codex session and a chat UI behind the same Magpie keep distinct
provenance without sharing one anonymous identity. The same value and the raw
agent name are recorded on imported Threads.
Each harness also gets its own recall cache: the same prompt from two harnesses
does not reuse the other's block. An explicit hostAgentId overrides the
derived value for all of them.
serverUrl: Mem base URL. If unset,NMEM_API_URL, thenhttp://127.0.0.1:14242.apiKey: Bearer API key. If unset, the variable named inapiKeyEnv.apiKeyEnv: environment fallback name, defaultNMEM_API_KEY; only anNMEM_*name is accepted. The environment key goes to the endpoint the hook resolves: pageserverUrlfirst, thenNMEM_API_URL. Keep the two paired; a page URL with an unrelatedNMEM_*key sends that key there.spaceId: Mem Space for recall, context and imports. Empty means the default Space.agentId: optional portable Mem agent profile. It selects a profile for the Context Bundle and is recorded on imported Threads; it is not authentication.hostAgentId: optional fixed host identity. Empty derivesmagpie:<agent>, ormagpiewhen Magpie reports no agent.recall: default true. Whether a turn gets Mem context. Recall only happens when a Mem endpoint is reachable; failures leave the request as it came.skipAgents: default empty. Apps this plugin leaves alone: their requests get no recall, Context Bundle or capture, and nothing about them reaches Mem. A list of names (["Mozilla", "Claude Code"]) or one comma-separated string. A name is the app's agent as Magpie's Usage page shows it; case, spaces and punctuation don't matter, soClaude Codeandclaude-codeare one app. A translator or other one-shot tool behind Magpie goes here (#597).contextBundle: default true. On a session's first turn, ask Mem for its Context Bundle (owner profile, rules and Working Memory) and add its rendered markdown. When the bundle is empty, missing or failing, the hook falls back to today's Working Memory. A bundle outage never disables Memory recall.maxMemories: how many search hits to consider, default 5, range 1–20.maxBytes: recall budget for the block's content, default 6000, range 512–32768. On the first turn the session context takes up to 45% of it, and the rest stays available for Memory.requestTimeoutMs: deadline for each search, bundle or Working Memory request, default 1500, range 50–30000. Magpie's default 1000 ms hook deadline can end the request earlier, so a longer value needs agatewayTimeoutMsat least as long. A deep search can take 20 seconds. The package's example options set this to 900 when used explicitly. Thread imports keep a separate ten-second deadline because a completed reply's notification is not bound to the live request.gatewayTimeoutMs(Magpie's own option, not this package's): the hook's deadline, default 1000 ms, range 100–30000. A local Mem fits the default; over the network, set it to 5000–10000 so the first turn's Context Bundle and search can finish, and higher for a slow deep search. A budget over 10000 ms needs Magpie 0.1.3538 or later; an older Magpie takes any value over 10000 as its 1000 ms default and stops the chain at 10 seconds.recallBackoffMs: after a connection failure, timeout or unavailable response, skip Mem for this endpoint/credential/Space for this long, default 30000, range 100–300000. A failing optional bundle backs off only itself; the Working Memory fallback keeps being tried. Client cancellation does not trigger backoff.capture: default false. Import completed conversations as Mem Threads. Set"capture": trueexplicitly to opt in.captureTools: default true. Include client tool results astoolmessages. Turn it off to import only what the user and the assistant wrote.captureFilter:"off"(default) or"human". Human mode stores only user/assistant text, including commentary attached to completed tool calls; it excludes tool results regardless ofcaptureTools. Only the saved copy changes. See capture filtering and its limits.captureCindy: default false. WithcaptureFilter: "human", remove complete known leading Cindy notes only when Magpie identifies the agent ascindy. Mixed scheduled or partner handoff text is conservatively retained; the protocol role does not establish authorship. It does not infer native Side Chat boundaries. Configure both options in Plugins → Options.allowInsecureHttp: default false. Permits plain HTTP to a server that is not a loopback address. Prefer HTTPS.recallRemote: default false. Recall and the Context Bundle go only to direct local requests andmagpie-keyfrom this computer. Set it to give recall also toremoterequests (another machine) andgateway-keyrequests (other gateway keys), which then receive what Mem recalls. It does not turn on saving. A missing or unknown origin never gets recall.captureRemote: default false. Withcaptureon, also save conversations fromremoteandgateway-keyrequests. It does not grant recall: withoutrecallRemotethose requests are saved but get nothing from Mem. The Settings page has separate switches for these options.port: the loopback port of the page's connection test, default 3479. Change it only when another program holds that port; the page reads the same value.
The latest user turn (Magpie's ctx.query, not client environment notices,
bounded to 2000 characters) is sent to POST /memories/search. On a session's
first turn the Context Bundle comes with it, or Working Memory when the bundle
is unavailable. The answer is wrapped in a <nowledge-mem-reference> block and
appended to that turn:
## Context bundle
<Mem's rendered Context Bundle>
## Recalled memories
### <title>
<Memory text>
nowledgemem://memory/<id> · relevance 0.94
When the bundle falls back, the heading is ## Working Memory instead. Each
Memory keeps its title and up to 1000 characters of text, and the whole section
stays within maxBytes.
The block says the text is untrusted historical evidence, not instructions. Recalled text cannot close the block it is in. A turn keeps the block it was given for the rest of the conversation, so the request prefix stays stable for the provider's prompt cache; a tool loop or a retry reuses it without asking Mem again. A turn that already carries this plugin's block, or Mem context injected by another connector (such as the DeepSeek Harness bundle), is left alone rather than given a second copy.
Nothing recalled means the request is returned unchanged. Timeouts, an unreachable server, an unknown Space and an unauthorized key all keep inference available; the Plugins page shows a fixed outcome code and byte count, never recalled text or a token.
With capture on, a completed reply is turned into the conversation the client
sent plus the assistant's reply, and imported with POST /threads/import:
thread_id:magpie-<session>-<digest>, or a digest of the opening turn for a client with no session. It stays the same across turns, so Mem appends missing messages instead of creating a Thread per turn.title: the first line of the message Magpie read as the user's query. A Thread keeps the title it opened with, so a client's environment notice before the real prompt does not become it.source:magpie;tool_version:magpie-nowledge-mem/<version>.metadata:source_app, protocol, the harness (agent), the host identity, an optional agent id, and SHA-256 digests of the session and working directory — not their raw values.
Messages are text only. Assistant tool-call steps with no text are not
messages; client tool results are included while captureTools is on and
captureFilter is "off". In "human" mode, the title comes from the first
retained user message and is cached after a successful import. The
recalled <nowledge-mem-reference> blocks are stripped before import, so
Memory is never learned as a new conversation. A conversation with a
credential-like assignment, URL password, bearer token or common key format in
its text or tool arguments is not captured at all — a best-effort safeguard,
not a guarantee. Each Thread import is one bounded request; conversations over
512 KiB are skipped, and an identical replay of the last successful import is
not sent twice. A failed import fails open and is not retried blindly.
capture is the only switch that exports conversation content. Recall works
without it. Filtering is opt-in and does not automatically migrate saved Threads;
see the migration notes.
The package adds no Library entry, no Magpie tool hook, no skill and no
system-prompt edit. To give agents Mem's tools, add Mem's official MCP server
once in Library › MCP, with <serverUrl>/mcp (or NMEM_API_URL when Server
URL is empty) and the connection's key. With the
MCP hub on, each agent still gets a single
magpie entry, and the tools are Mem's own, not a second surface.
The page shows the effective Server URL in its summary; it does not add the Library entry itself. If you want a custom system prompt for Memory, Magpie's system-prompt middleware does that on its own.
bun test packages/nowledge-mem # offline tests
node --test packages/nowledge-mem/capture-filter.test.mjs # focused capture contract
NMEM_E2E=1 bun test packages/nowledge-mem # also the live checks, when .env is set
bun packages/nowledge-mem/e2e.run.mjs # the live checks aloneThe hook tests fake Mem with fetch: no server, no sign-in and no network. The
end-to-end checks talk to a real Mem and are skipped unless NMEM_E2E=1; they
read the repository's .env (the file wins over an ambient NMEM_API_URL or
NMEM_API_KEY):
set -a; . ./.env; set +a
bun packages/nowledge-mem/e2e.run.mjsThe checks create a few Memories and Threads per run and delete them afterwards.
They verify that .env reaches Mem, that recall returns a seeded Memory and
cites its id, that the Context Bundle arrives on a session's first turn, that
capture creates one Thread and appends only the new messages idempotently, that
the Thread records the harness and host identity, and that a wrong key and an
unknown Space report fixed codes. e2e.test.mjs runs them in a process of its
own: the offline tests replace globalThis.fetch to keep Cursor's token local
(packages/cursor/nonet.mjs), and a live check must not share that process.
The page uses Magpie's released magpie.options and theme bridge. Before
saving it re-reads and merges edited fields, but another write between the read
and write can still be lost. The released bridge can also round integers outside
JavaScript's exact range, including in unlisted options. Use one editor at a time. It
declares no reads and saving stores configuration without probing the
connection or writing Memory. It shows connection, local and remote recall, apps excluded with skipAgents, local and remote capture, filtering and advanced options. Its What is sent section says
the scope: direct local requests and magpie-key from this computer; other
gateway keys and remote requests require separate recallRemote or captureRemote opt-ins. It follows Magpie's language (English, Simplified and
Traditional Chinese, Japanese, German) and theme, and preserves options it does
not show.
Test connection is a real check, not a saved flag. Magpie's page sandbox
has connect-src 'none', so the page cannot call Mem itself; the package's
small host part serves a loopback page on 127.0.0.1:<port> and the frame
navigates to it. The Test connection button tests the saved options, so
save changes first. The language travels in the test URL's query; the test
page asks for a click, then the service reads the saved plugin options itself
and makes one public health request and one authenticated Working Memory
request. No URL, key, Space or return address travels through the page. It
writes nothing and shows reachability, the key and the Space with a fixed code
and milliseconds. Back to settings uses the frame's history to return to
the plugin page; the test saves nothing and changes no form values.
The helper binds 127.0.0.1, answers only when Host is 127.0.0.1:<port> or
localhost:<port>, and needs the page's per-process token. Its JSON endpoint
accepts Origin: null from the sandboxed page and nothing else, and returns no
access-control-allow-origin: *; POST and the page's fetch are therefore
closed to other sites. The test page takes no return address; its Back button
only walks the frame's history. Because the Host must be loopback, the test
works in the desktop app, not through a remote magpie web proxy.
The test needs the plugin host, which the gateway hook already starts; a page-only install of an older Magpie version shows the test page failing to connect rather than a wrong result.