Shared, permissioned, live memory for agents and people, as a Harper plugin.
Scoped visibility (global, user:<id>, customer:<id>, team:<id>) with grants on Harper users and roles
Hybrid search (vector + full-text, reciprocal rank fusion) that covers a memory as soon as its write commits
First-class supersession: replacing a memory hides the old one from default search, and withdrawing the replacement restores it
Write-time supersession candidates: every PUT returns the similar memories it may replace, optionally classified by a judge model, which auto mode can act on
Provenance flags: when a memory is superseded or withdrawn, the memories citing it as evidence get needsReview until their owner revises or confirms them
Customer-content flag: a global write that names a configured customer, or matches a configured host pattern, is committed but readable only by its owner and customer:* readers until a reviewer rescopes or confirms it; an optional model check runs after commit
Live updates: Level 1 real-time subscriptions on /Memory and /Memory/<id> (SSE, WebSocket) with delivery-time read checks, and Level 2 watches (POST /Memory/watch, watch=true on search/bootstrap) delivered with own needsReview flags on /MemoryEvents
Extension points: registerMemorySink runs inside the lifecycle transaction for apps that mirror memories elsewhere, setPrincipalResolver maps app-defined identities, resolvePrincipal / canReadLabels let other components authorize with the same identity and grants, and scanMemories, getMemories, registerBootstrapSection and let a plugin build derived data over memories and add it to bootstrap and search results
Status: v0 (0.x releases may change contracts; see CHANGELOG.md). Design and contracts:
DESIGN.md.
Install
npm install @harperfast/agent-memory
harper (^5.3.1: 5.3.1 or later within 5.x) is a peer dependency: the host app provides it. Enable the plugin
under its package name in the host app's config.yaml, as in step 1 below.
Quick start
Requires Harper 5.3.1 or later within 5.x, on RocksDB (the default).
Add the plugin and an embedding model to the host app. The plugin embeds with the model named by
embeddingModel (default default), so any Harper embedding backend works:
# host app config.yamlrest: true'@harperfast/agent-memory': package: '@harperfast/agent-memory' # urlPath: 'Memory' # mount path (watch stream mounts at '<urlPath>Events') # mcp: false # expose MCP tools and memory:///{id} on Harper's /mcp endpoint # embeddingModel: 'default' # logical model name from Harper's models config # embeddingTruncate: false # Harper 5.4+: the model cuts each input at its own token window, when its entry # # can truncate (OpenAI-compatible vLLM with truncation: 'vllm', Ollama, Bedrock # # Cohere). When it cannot, or on Harper 5.3, input is cut to # # limits.embeddingFallbackChars instead, with a warning # lockScope: 'node' # 'cluster' serializes lifecycle writes across nodes; set it on every node, and only # # with record locks on the memory database, or every write answers 503 # limits: # contentChars: 20000 # longest memory content accepted # embeddingInputChars: 6000 # leading characters of content (and of a search query) sent to the embedding # # model. Characters, not tokens: lower it for a small window or token-dense text # # (CJK, code), unless embeddingTruncate is on. Full-text search covers the rest. # embeddingFallbackChars: 4000 # with embeddingTruncate on, the bound used when the model cannot truncate # # (never above embeddingInputChars); set it to what fits without the model's cut # supersession: # similarity: 0.82 # candidates returned on PUT at or above this cosine similarity # judge: 'judge' # a generative model that classifies each candidate # mode: 'suggest' # 'off', or 'auto' (needs judge): apply "supersedes" verdicts on create # customerContentCheck: # absent = off # mode: 'flag' # or 'off': stop checking (existing flags stay enforced) # model: 'content-check' # optional generative model, asked after commit # patterns: # namesFile: '/etc/agent-memory/customer-names.json' # absolute path, never in a repo; or: # namesSecret: 'AGENT_MEMORY_CUSTOMER_NAMES' # a component secret: { "<org>": ["Name", "Alias"] } # hosts: # - { label: 'cloud-host', host: '*.example-cloud.com' } # an exact host, or any subdomain with '*.' # - { label: 'lab-ip', cidr: '10.77.0.0/16' } # an IPv4 or IPv6 address or range
# harperdb-config.yamlauthentication: authorizeLocal: false # required when behind a local reverse proxy so loopback requests are not treated as super_usermodels: embedding: default: { backend: openai, model: text-embedding-3-small, apiKey: '${OPENAI_API_KEY}' }
Grant scopes. Every user implicitly reads and writes user:<self>; super_user reads and writes
everything. Other labels come from ScopeGrant rows keyed role:<role> or user:<username>:
# create (client-chosen id, 16-64 URL-safe chars; private by default, `visibility: "shared"` means global, or pass `scopes`)curl -u carol:pass -X PUT localhost:9926/Memory/<id> -H 'Content-Type: application/json' -d '{ "title": "Disk saturation", "content": "Stalls above 30% iowait.", "scopes": ["customer:acme"], "tags": ["ops"] }'curl -u carol:pass 'localhost:9926/Memory/?q=iowait&limit=5' # hybrid searchcurl -u carol:pass 'localhost:9926/Memory/bootstrap?q=disk&budget=8000' # session-start contextcurl -u carol:pass -i localhost:9926/Memory/<id> # read (returns ETag: "<revision>")# revise, change scopes, or withdraw: pass If-Match with the revision ETag you readcurl -u carol:pass -X PUT localhost:9926/Memory/
A memory the caller cannot read returns the same 404 as a missing one. POST /Memory/import bulk-loads
rows with preserved owners and timestamps (super_user only); see DESIGN.md.
Extension points
import { canReadLabels, registerMemorySink, resolvePrincipal, setPrincipalResolver } from '@harperfast/agent-memory';// Runs inside the lifecycle transaction. Writes through `context` to a table declared in the `memory`// database (`@table(database: "memory")`) commit or roll back with the memory; a table in another database// commits separately and can lose a row on a crash. Throwing aborts the operation.const outbox = databases.memory.MemoryOutbox;registerMemorySink({ async write(memory, context) { await outbox.put({ id: `${memory.id}:${memory.revision}`, memoryId: memory.id }, context); }, async withdraw(memory, context) { await outbox.put({ id: `${memory.id}:${memory.revision}`, memoryId: memory.id, withdrawn: true }, context); },});// Map your own credentials to a principal; `next()` is the default Harper-user resolution.setPrincipalResolver(async (context, next) => (await lookUpAgentKey(context)) ?? next());// Authorize your own records with the same identity and grants. The principal is frozen:// { id, superUser, source, read: ['user:alice', 'global', 'customer:*'], write: [...] }// Rejects with statusCode 401 (code 'principal_required') when there is no caller.const principal = await resolvePrincipal(context);const visible = records.filter((record) => canReadLabels(principal, record.scopes));
A plugin that builds something over memories (topic summaries, say) reads them with scanMemories, stays current
with a sink, and serves its output beside memories:
import { canReadLabels, getMemories, registerBootstrapSection, registerSearchAnnotator, scanMemories,} from '@harperfast/agent-memory';// Every active, unexpired memory as stored (embedding included), oldest first. Pass the last row's// { createdAt, id } as `after` to resume; `includeInactive: true` also yields superseded, withdrawn and expired rows.for await (const memory of scanMemories({ after: savedCursor })) await index(memory);// The rows for ids you already track, in that order, in every status; ids with no row are left out.const members = await getMemories(cluster.memoryIds);// Packed into GET /Memory/bootstrap after pinned and needsReview, before recent, within the caller's budget.registerBootstrapSection({ name: 'orientation', render: async ({ principal, q, budgetChars, context }) => (await topicsFor(principal, budgetChars)).map((topic) => ({ title: topic.title, content: topic.summary })),});// Adds hit.summaries to GET /Memory/?q= and MCP recall results; cannot add, drop or reorder hits.registerSearchAnnotator({ name: 'summaries', annotate: async ({ principal, hits, context }) => new Map(await summariesFor(principal, hits)),});
The scan takes no principal: it is for trusted plugin code. Sections and annotators receive the caller's principal,
and agent-memory shows what they return as is, so they must show a caller only what that caller may read: all of
the memories a summary draws on, judged by their current scopes and content flags. A section or annotator that
throws is left out and logged; the request still succeeds. Contract: DESIGN.md.
read and write list the effective grant patterns: user:<id>, exact labels and namespace wildcards, with
role and user grants merged and patterns that grant nothing dropped. A super_user's lists do not enumerate its
access; check superUser, or let canReadLabels do it. canReadLabels is the label rule only (any label
matches), and accepts only a principal resolvePrincipal returned. Contract: DESIGN.md.
From another app
These functions also work in an app that imports the package without listing the plugin, while
agent-memory runs as its own app on the same Harper, for example so it can be upgraded separately. That app's
copy of the package registers with the running plugin and asks it to resolve principals. Its sinks run inside the
plugin's lifecycle transaction, and its authorization matches the plugin's routes even when the two versions
differ. This needs:
Both apps on Harper's shared worker pool: agent-memory must not be isolated.
Harper's default module loading: applications.moduleLoadervm-current-context (the default) or vm, and
applications.dependencyLoader unset or app. Under the native or compartment loader each copy keeps its
own state, as before, so this does not work there, and nothing warns. With dependencyLoader: native, a copy
that registers beside a running plugin logs a warning.
Exactly one app listing the plugin in its config.yaml. A second one fails to load. Which of the two loads
first can differ from worker to worker, so remove one.
A version of this package newer than 0.1.3 in the importing app. 0.1.3 and earlier keep registrations to
themselves. Bootstrap sections and search annotators also need a running plugin newer than 0.1.4; beside 0.1.4
they are never used, and registering one logs a warning.
To move the plugin out of a host app:
Upgrade the host app's dependency first. It keeps working in-app.
In one deploy, add the agent-memory app, with the plugin options moved into its config.yaml, and remove
the plugin entry from the host app.
Rolling the host back to 0.1.3 or earlier stops its sinks.
Claude Code plugin
The repository ships a Claude Code plugin in claude-plugin/ (registered in
.claude-plugin/marketplace.json) that wires agent-memory's remote
HTTP /mcp endpoint, automatic SessionStart bootstrap, budgeted UserPromptSubmit recall, and live
/MemoryEvents change notices into Claude Code.
Install & configure
Enable mcp: true under @harperfast/agent-memory in your Harper app's config.yaml.
Add the marketplace and install the plugin in Claude Code:
Set AGENT_MEMORY_URL in your shell or Claude Code settings.jsonenv block (so .mcp.json can
expand ${AGENT_MEMORY_URL}/mcp) and store AGENT_MEMORY_TOKEN in ~/.config/agent-memory/env
(chmod 600 ~/.config/agent-memory/env):
Keep in Claude's native file memory (~/.claude/projects/.../memory/): machine-specific paths,
local worktree/harness state, and personal workflow preferences.
Never duplicate: never write the same fact to both stores.
Migration & recall evaluation scripts
# Preview or migrate native Claude memory files into agent-memory (default scope: user:<self>)node scripts/import-claude-memory.mjs --dry-run ~/.claude/projects/<project>/memory/node scripts/import-claude-memory.mjs --delete-migrated ~/.claude/projects/<project>/memory/feedback_testing.md# Evaluate recall@k and latency for the recall hook's query against a JSONL dataset of { prompt, expectedIds }node scripts/eval-recall.mjs --dataset eval.jsonl --k 5
Development
npm test # build + unit tests (in-memory harper stub)npm run install:fixtures # pack the plugin into the integration fixture appnpm run test:integration # boots Harper with the fixture and exercises the HTTP surface
Releasing
Open a PR that runs npm version <version> --no-git-tag-version and adds a dated CHANGELOG.md entry for that
version. npm version bumps package.json and package-lock.json and writes PACKAGE_VERSION in
src/version.ts, the version the running plugin advertises to other apps; a unit test fails when they differ.
After it merges, publish a GitHub release tagged v<version> from main. The
release workflow refuses a tag that does not match package.json, runs the
unit and integration tests, and publishes the tested tarball to npm with provenance through trusted
publishing (no token). Prerelease versions (0.2.0-beta.1) publish to the next dist-tag; others to
latest.
npm trusted publishing is configured per package on npmjs.com, so a package that does not exist yet cannot use
it. Bootstrap:
An npm org owner publishes the first version by hand: npm ci && npm publish --access public in a clean
checkout of the v0.1.0 tag (no provenance for this version).
Publishing the v0.1.0 GitHub release runs the workflow; its publish step fails, which is expected for this
one release.
Shortly before the next release, add a Trusted Publisher on npmjs.com: HarperFast/agent-memory,
release.yml, environment Release, with direct npm publish allowed (new configurations default to
npm stage publish only). A configuration expires unless it completes a publish within 2 days.
Provenance requires a public repository.
Import
scripts/import-flair.mjs copies memories from a Flair instance
into an app running this plugin, through POST /Memory/import. Run it from a checkout (Node 22+); it
has no dependencies (--classifier anthropic needs the @anthropic-ai/sdk dev dependency) and is not part of
the published package. Mapping rules: DESIGN.md.
# 1. Preview: counts and ids only, nothing sent to the targetFLAIR_ADMIN_PASS=… node scripts/import-flair.mjs --flair https://flair.example.com \ --snapshot flair-memories.jsonl --principal-map principals.json --dry-run# 2. Import from the frozen snapshotAGENT_MEMORY_USER=… AGENT_MEMORY_PASS=… node scripts/import-flair.mjs \ --from-jsonl flair-memories.jsonl --principal-map principals.json --target https://app.example.com
When shared Flair memories may hold customer detail, classify before step 2 instead of importing them as
global (DESIGN.md):
# 2a. Propose scopes and lesson drafts; writes the report onlynode scripts/import-flair.mjs --from-jsonl flair-memories.jsonl --principal-map principals.json \ --classify --lessons --org-map orgs.json --report classification.json# 2b. Review and edit classification.json (scopes, slugs, lessons), then import what it saysAGENT_MEMORY_USER=… AGENT_MEMORY_PASS=… node scripts/import-flair.mjs \ --from-jsonl flair-memories.jsonl --principal-map principals.json \ --decisions classification.json --target https://app.example.com
Option
Meaning
--flair <url>
Read every memory live from Flair (GET /Memory/ as the Flair admin)
--snapshot <file>
With --flair: also write the rows read to a new JSONL file (mode 0600, never overwritten)
--from-jsonl <file>
Read raw Flair Memory rows, one per line (a --snapshot file, or memories.jsonl from a Flair REM snapshot)
Base URL of the app; rows go to <url>/Memory/import
--dry-run
Print the mapping summary and stop
--batch-size <n>
Rows per request, 1–100 (default 100)
--max-content-chars <n>
Content length limit, 1–100000 (default 20000; match the target's limits.contentChars)
--classify
Propose a scope for every row that would be global; needs --report, contacts no target
--report <file>
With --classify: the report to write (mode 0600, never overwritten)
--org-map <file>
With --classify: JSON object mapping organization names and aliases to slugs: { "Acme Corp": "acme" }
--lessons
With --classify: also draft a sanitized global lesson for each active customer record
--classifier <name>
With --classify: claude (default; the local Claude Code CLI) or anthropic (ANTHROPIC_API_KEY)
--classifier-model <id>
With --classify: the model the classifier uses
--concurrency <n>
With --classify: model calls in flight, 1–16 (default 4)
--decisions <file>
Import with an edited report applied (with --dry-run or --target); makes no model calls
Credentials come only from the environment: FLAIR_ADMIN_USER (default admin) and FLAIR_ADMIN_PASS
for Flair, AGENT_MEMORY_USER and AGENT_MEMORY_PASS (a super_user) for the target. URLs must be
https (plain http only for loopback hosts) and must not embed credentials.
The summary (JSON on stdout) counts rows by owner, scope and status, and lists what was skipped
(unmapped agents, ephemeral rows, rows outside content/tag limits), supersedes links that were dropped (missing, skipped, self,
cycle, or narrowing when the replacement would hide the old memory from some of its readers), and
Flair visibility values other than private/shared (imported as global). It never contains memory
content. The whole export is held in memory while it is mapped.
Before importing, check that the principals who read shared Flair memories hold global read in the
target.
A failed batch stops the run; earlier batches stay committed. Re-run the same command from the same
snapshot and principal map: rows already imported come back unchanged, and a row that was edited in
the target since comes back conflict and is left alone. A live --flair re-run reads Flair again, so
rows changed in Flair since the first run also come back conflict; import from a snapshot to avoid that.
Do not edit imported memories in the target until the import has finished. The result lists conflicted
rows (conflicts) and the rows superseded by one of them (dependsOnConflict); check those
by hand.
Classification sends each shared memory to the chosen model, so run it on your own machine, never on a
fleet worker. The report holds customer detail: keep it private and delete it after the import. In the
report, each row has scopes (["global"] or customer:<slug> labels), the organizations found,
a one-sentence rationale, and lesson (null for none, or { title, content }). Rows the
classifier could not decide are customer:unclassified, readable only by customer:* holders.
newOrganizations and slugCollisions list the slugs to check. --decisions refuses a report whose
rows no longer match the source, so re-run --classify after the source changes. Sources are imported
first; a lesson goes in only when its source is stored as imported and still active (lessons.skipped
lists the rest). Re-applying never withdraws a lesson an earlier apply published: an edited lesson comes
back conflict, and a removed one stays. Withdraw it in the target. Rows a plain import already sent as global come back conflict and keep their
scopes. The claude classifier runs claude -p with your login and no tools, plugins, hooks or
project instructions, except hooks your administrator manages. If such a hook forwards prompts, use
--classifier anthropic. Owners always read their own memories, so map no Flair agent to a fleet
principal.
Copy between instances
scripts/copy-memories.mjs copies every memory of one app running this plugin into another, for example from a
test deployment to its permanent home. Ids, owners, scopes, createdAt, supersession links, withdrawn and expired
memories, content flags and pending review flags carry over; the target re-embeds with its own model. Run it from a
checkout (Node 22+), as a super_user of both apps. Both must run a plugin version with includeWithdrawn (the
script refuses one that does not acknowledge it). Rules: DESIGN.md.
export AGENT_MEMORY_FROM_AUTHORIZATION="Basic $(printf '%s' 'admin:…' | base64)" # the source's super_userexport AGENT_MEMORY_TO_AUTHORIZATION="Bearer …" # the target's super_user# 1. Preview: source counts by status and scope, and the target check; nothing is writtennode scripts/copy-memories.mjs --from https://test.example.com --to https://app.example.com --dry-run# 2. Copy, then verify every row; re-running resumes an interrupted copy and reports every row unchangednode scripts/copy-memories.mjs --from https://test.example.com --to https://app.example.com
Option
Meaning
--from <url>
Base URL of the source app
--to <url>
Base URL of the target app (optional with --dry-run)
--batch-size <n>
Rows per import request, 1–100 (default 100)
--dry-run
Read only
Stop writers first. Copy at cutover, with no agent writing to either app, and wait a minute after the last
write so any pending customer-content model check has ruled (its call times out at 30 seconds). After the copy, the script reads the source again
and fails if anything changed since it was read (sourceChanged). A memory missing from the copy is picked up by a
re-run; one that changed on the source after it was copied makes the next run refuse rather than overwrite.
One target node.--to must reach a single Harper node, not a load balancer over several: each batch relies
on the previous ones being visible, which replication lag between nodes does not guarantee.
The target must hold only this copy. Before writing, the script compares every target memory with the source
and refuses if the target has a memory of its own or one that differs. Exit status is 0 only when the final
comparison matches.
Same people, same grants. Labels are copied as they are, so user:alice and every ScopeGrant must mean the
same on the target. Grants, pins and watches are not copied; recreate the ScopeGrant rows by hand.
Not carried: revision numbers, author and last editor (the target records source: import), confirmed,
scopeConfirmed (the target's own check may flag a memory again for review), and which links the judge added. The
dry run counts the rows that lose one.
Stdout and stderr carry ids, counts, scope labels and codes only.
Supersession backfill
Imported history rarely records which memory replaced which. scripts/backfill-supersession.mjs finds
those pairs with the server's own supersession candidates, has a model judge each pair, and links only
the pairs you approve. Run it from a checkout (Node 22+) on your own machine, as a super_user of the
target; --judge anthropic also needs the checkout's dev dependencies (npm ci). Rules: DESIGN.md.
# 1. Report: judge every (newer, older) candidate pair; writes a new 0600 file, links nothingAGENT_MEMORY_USER=… AGENT_MEMORY_PASS=… node scripts/backfill-supersession.mjs \ --target https://app.example.com --report backfill-report.json# 2. Review: set "approve": true on each "supersedes" pair to link (or approve them all after reading them)jq '.pairs |= map(.approve = (.verdict == "supersedes"))' backfill-report.json > backfill-decisions.json# 3. Apply the approved pairs, newest replacement first; re-running links nothing newAGENT_MEMORY_USER=… AGENT_MEMORY_PASS=… node scripts/backfill-supersession.mjs \ --target https://app.example.com --apply backfill-decisions.json
Option
Meaning
--target <url>
Base URL of the app
--report <file>
Write the judged pairs to this new file (never overwritten)
--apply <file>
Link the approved supersedes pairs of an edited report
--judge <backend>
claude (default: the local Claude Code CLI on your login, never an API key), anthropic (ANTHROPIC_API_KEY)
--model <id>
Model for the judge (default: the CLI's own default; claude-opus-5-5 for anthropic)
--concurrency <n>
Judge calls in flight, 1–16 (default 4)
The report lists, per pair, both ids and titles, the similarity, the verdict and a one-sentence
rationale, but no memory content; stdout and stderr carry only ids, counts and codes. Apply skips a pair
whose memories changed since they were judged, or were withdrawn, and reports any link the server refused
with its code. The claude judge runs the CLI with --safe-mode, so your CLAUDE.md, hooks and plugins
never see the memories; if your machine has managed (policy) hooks that forward prompts, use
--judge anthropic.