goodmemory
Advanced tools
GoodMemory 是一个面向 chatbox、copilot、AI agent 等 AI 应用的可插拔用户记忆层 memory layer。
它的定位不是 memory database，也不替代： - LLM - agent framework - 向量数据库 - RAG 系统 它专注解决一个更具体的问题： > 如何让任何 chatbox / copilot / agent / workflow assistant 在不重训模型的前提下，真正“记住用户”。 GoodMemory 的核心不是“存更多”，而是： - 记什么 - 何时更新 - 如何检索 - 如何压缩 - 为什么引用 - 如何删除 - 如何控制跨 agent / 跨项目 / 跨租户边界 它的本质是一个： > Personal Context Engine / Memory Layer for AI Apps
核心闭环只有 5 件事：
remember()recall()buildContext()feedback()forget()import { createGoodMemory } from "goodmemory";
const memory = createGoodMemory({});
await memory.remember({
scope: { userId: "u-1", sessionId: "s-1" },
messages: [
{
role: "user",
content: "Remember that the migration rollout is blocked.",
},
],
});
const recall = await memory.recall({
scope: { userId: "u-1", sessionId: "s-2" },
query: "How should I answer this user?",
retrievalProfile: "general_chat",
});
const context = await memory.buildContext({
recall,
output: "markdown",
});
Domain-specific writes are configured through the public remember surface on
createGoodMemory. Use profiles and rules when a host knows what should become
durable memory for a specific agent or domain. Do not use testing.extractor
for product integrations; that seam is for tests.
import { createGoodMemory, rememberRules } from "goodmemory";
const memory = createGoodMemory({
remember: {
preset: "default",
profiles: [
{
id: "life-coach",
when: { agentId: "life-coach" },
rules: [
rememberRules.fact(/my top priority this quarter is (.+)/i, {
id: "life-goal-priority",
category: "goal",
tags: ["life_coach", "long_term_goal"],
attributes: { horizon: "quarter" },
content: ({ match }) => match[1] ?? "",
}),
rememberRules.preference(/please coach me with (.+)/i, {
id: "life-coaching-style",
category: "coaching_style",
value: ({ match }) => match[1] ?? "",
}),
],
assistantOutputs: { mode: "confirmed_or_verified_only" },
},
],
},
});
await memory.remember({
scope: { userId: "u-1", agentId: "life-coach" },
messages: [
{
role: "user",
content: "My top priority this quarter is rebuilding my sleep routine.",
},
],
annotations: [
{
messageIndex: 0,
remember: "always",
metadataPatch: { tags: ["confirmed_by_host"] },
},
],
});
Assistant messages are ignored by default for durable writes. To make an
assistant-originated suggestion durable, the host must annotate the message and
the selected profile must allow confirmed or verified assistant output.
remember: "never" suppresses the annotated message before deterministic,
custom, or assisted extraction.
Profile extractors can be supplied either as raw MemoryExtractor objects or
as { id, extractor } entries. Use the named form for product integrations so
remember events and eval reports carry stable extractorIds even if the profile
composition order changes. Named ids must be non-blank, unique within the
resolved profile, and outside the generated raw-extractor id namespace
${profileId}:extractor-N; invalid ids fail during profile resolution.
Remember events also carry the resolved profileId and presetId for default,
custom, assisted, and annotation-derived writes.
GoodMemory 0.1.2 now exposes a Node-compatible packaged library boundary for:
goodmemorygoodmemory/ai-sdkgoodmemory/hostThe installed CLI remains Bun-backed today.
Published install:
npm install goodmemory@0.1.2
Bun install:
bun add goodmemory@0.1.2
Tarball verification for release rehearsal before publish:
npm install ./goodmemory-0.1.2.tgz
The default runtime contract stays low-friction:
createGoodMemory({})./.goodmemory/memory.sqlitesqlite / postgres storage on unsupported runtimes is reported as unavailable, not durabledocumentStore / sessionStore / vectorStore are injected, runtime inspection reports adapter-defined storage instead of guessing built-in durabilityGOODMEMORY_EMBEDDING_*, runtime stays rules-onlyIf your integration cares about durability, inspect the resolved runtime after construction instead of assuming Bun-style local persistence:
import { createGoodMemory, inspectGoodMemoryRuntime } from "goodmemory";
const memory = createGoodMemory({});
const runtime = inspectGoodMemoryRuntime(memory);
GoodMemory 0.1.2 自带一个 Bun-backed 的已安装 CLI。包里的 goodmemory bin 现在可以在 Node 包安装场景下安全暴露；真正执行命令时会委托给 Bun。稳定的 memory-first 命令仍然是 inspect / trace / export-memory / stats / eval ...。显式 --storage-provider / --storage-url 优先；不显式指定时，会优先尝试可用的 Postgres 目标，否则在 Bun 运行时回落到当前工作目录下的 sqlite：./.goodmemory/memory.sqlite。这些 memory-first 根命令只会读取已有存储；如果最终解析到的本地 sqlite 不存在，CLI 会报错而不会隐式创建本地数据库。唯一的策略诊断例外是 trace --ignore-memory：它会把 recall 视为空集并直接跳过存储解析。
Version checks are intentionally lightweight and follow the normal package-bin contract:
./node_modules/.bin/goodmemory -V
./node_modules/.bin/goodmemory --version
The installed Node wrapper answers version queries directly without launching Bun. Other CLI commands still delegate to Bun.
Phase 35 installed-host middleware commands are now part of the accepted stable host surface. The recommended entrypoint is goodmemory setup, which detects Codex and Claude Code, installs managed host wiring, and defaults interactive installs to global activation. goodmemory status [codex|claude] reports host wiring, activation mode, current workspace status, storage, managed MCP/hook registration, writeback mode, and scoped memory counts without initializing fresh local SQLite state. The host-specific goodmemory install|uninstall <codex|claude> and goodmemory enable|disable <codex|claude> commands remain available for advanced control, while the lower-level goodmemory codex bootstrap / goodmemory claude bootstrap commands stay supported compatibility paths for artifact-first integrations.
The accepted installed hook runtime commands are the canonical always-on recall path when a repository or global activation mode is enabled: goodmemory codex hook <session-start|user-prompt-submit> and goodmemory claude hook <session-start|user-prompt-submit>. session-start and user-prompt-submit read host hook JSON from stdin, use the existing recall() + buildContext() path, and fail open when config, opt-in, parsing, or recall is unavailable.
The read-only MCP surface is accepted for deep read, debug, and artifact browsing: goodmemory mcp serve --host <codex|claude> and goodmemory-mcp --host <codex|claude>. MCP does not replace hook-time recall injection or the Phase 34 host pre-action path.
The explicit write CLI commands goodmemory remember, goodmemory feedback, and goodmemory forget remain accepted for installed-host seeding and correction.
goodmemory codex writeback is the accepted opt-in installed-host after-response/session-end write path. goodmemory claude writeback follows the same deterministic surface, while Codex remains the canonical live-evidence path.
Writeback is disabled by default. Use observe before selective:
goodmemory enable codex --writeback observe
goodmemory enable codex --writeback selective
Writeback does not persist raw transcripts. It extracts selected memory candidates and writes them only through the public remember surface, using installed-host profiles, rules, annotations, and the Phase 36 assistant-output policy. Assistant-originated durable memory requires host confirmation or verification, and remember: "never" masks annotated content before extraction. session-stop hook payloads delegate to the same writeback runtime when a host invokes that hook.
Writeback is auditable and reversible from the installed-host CLI:
goodmemory codex writeback inspect --json
goodmemory codex writeback forget --event-id <event-id> --review-outcome false_write
The audit ledger stores bounded redacted candidate previews, candidate keys, typed linked record ids, status, reasons, host, mode, timestamps, scope/session digests, and optional manual review metadata. It does not store raw host payloads. forget --event-id deletes the linked memory/evidence records through the public forget() API before marking the audit event forgotten.
Use goodmemory codex writeback for opt-in automatic writeback, goodmemory remember / goodmemory feedback for explicit seeding and correction, goodmemory codex hook user-prompt-submit for automatic recall injection, and goodmemory forget or goodmemory codex writeback forget for cleanup.
Installed-host setup is designed as a closed loop. In an interactive terminal,
goodmemory setup is the recommended happy path. It asks which host to enable,
where memory enhancement should run (global, current-workspace, or
manual), then prompts for the GoodMemory user id, optional Postgres storage,
optional embedding provider, optional LLM extraction provider, and the
installed-host writeback mode. goodmemory install <codex|claude> uses the same
host-specific wizard. Global activation is the default interactive path, while
--json and --no-interactive keep install script-safe; non-interactive
install remains workspace opt-in unless --activation-mode global is passed.
If you skip provider setup, install still succeeds with the local SQLite +
rules-only baseline.
goodmemory setup
goodmemory status
To configure stronger memory non-interactively, pass Postgres, embedding, and LLM extraction flags:
goodmemory install codex \
--user-id <user-id> \
--storage-provider postgres \
--storage-url "postgres://user:pass@host:5432/goodmemory" \
--embedding-provider openai \
--embedding-model text-embedding-3-small \
--embedding-api-key <key> \
--llm-provider openai \
--llm-model gpt-4o-mini \
--llm-api-key <key>
If you skip prompts or flags, the install output points to the managed file to
edit later: ~/.goodmemory/codex.json or ~/.goodmemory/claude.json.
Re-running goodmemory install <host> with provider flags updates the same
managed config and keeps MCP/hook registration idempotent. The installed hook,
MCP, and --host write commands read this managed config directly; shell
environment variables are still supported by the lower-level core runtime, but
they are not required for the installed-host path.
Package upgrade and GoodMemory host uninstall are separate operations. Upgrade the package through the same package manager you used to install it:
npm install goodmemory@latest
bun add goodmemory@latest
npm install ./goodmemory-<version>.tgz
Package upgrade replaces the package/bin files; it does not delete
~/.goodmemory, repo-local .goodmemory, local SQLite memory files, or remote
Postgres data. Package uninstall follows the same rule:
npm uninstall goodmemory
bun remove goodmemory
To remove managed host wiring, use GoodMemory's own reversible uninstall:
goodmemory uninstall codex
goodmemory uninstall claude
This removes GoodMemory-managed host config, hooks, and MCP registration for the
target host. It does not delete memory data. Clearing memory is an explicit data
operation (goodmemory forget ...) or a manual storage deletion after backup.
./node_modules/.bin/goodmemory inspect --user-id <user-id> --workspace-id <workspace-id>
./node_modules/.bin/goodmemory trace --user-id <user-id> --workspace-id <workspace-id> --query "Which runbook is the source of truth?"
./node_modules/.bin/goodmemory export-memory --user-id <user-id> --workspace-id <workspace-id> --output ./tmp/export
./node_modules/.bin/goodmemory stats --user-id <user-id> --workspace-id <workspace-id>
./node_modules/.bin/goodmemory remember --user-id <user-id> --workspace-id <workspace-id> --session-id <session-id> --message "Remember that the deploy is blocked on smoke verification."
./node_modules/.bin/goodmemory feedback --host codex --workspace-root . --session-id <session-id> --signal "Keep coding summaries short and list explicit next steps."
./node_modules/.bin/goodmemory forget --host codex --workspace-root . --session-id <session-id> --memory-id <memory-id>
./node_modules/.bin/goodmemory -V
./node_modules/.bin/goodmemory setup --host codex
./node_modules/.bin/goodmemory status codex --workspace-root .
./node_modules/.bin/goodmemory install codex --activation-mode global --writeback observe --user-id <user-id>
./node_modules/.bin/goodmemory enable codex --workspace-root . --writeback selective
printf '%s' '{"cwd":".","session_id":"s-1","hook_event_name":"SessionStart","source":"startup"}' | ./node_modules/.bin/goodmemory codex hook session-start
printf '%s' '{"cwd":".","session_id":"s-1","messages":[{"role":"user","content":"Next step is to finish the release smoke."}]}' | ./node_modules/.bin/goodmemory codex writeback --json
printf '%s' '{"cwd":".","session_id":"s-1","event_id":"stop-1","summary":"Keep coding summaries short."}' | ./node_modules/.bin/goodmemory codex hook session-stop
./node_modules/.bin/goodmemory mcp serve --host codex
./node_modules/.bin/goodmemory-mcp --host codex
./node_modules/.bin/goodmemory codex bootstrap --user-id <user-id> --workspace-id <workspace-id>
./node_modules/.bin/goodmemory claude bootstrap --user-id <user-id> --workspace-id <workspace-id>
./node_modules/.bin/goodmemory eval inspect --run-dir reports/eval/live/<run-id> --case-id <case-id>
./node_modules/.bin/goodmemory eval trace --run-dir reports/eval/live/<run-id> --case-id <case-id>
./node_modules/.bin/goodmemory eval export-case --run-dir reports/eval/live/<run-id> --case-id <case-id> --output /tmp/case.json
CLI surface:
goodmemory -Vgoodmemory --versiongoodmemory setupgoodmemory inspectgoodmemory tracegoodmemory export-memorygoodmemory statsgoodmemory statusgoodmemory remembergoodmemory feedbackgoodmemory forgetgoodmemory installgoodmemory uninstallgoodmemory enablegoodmemory disablegoodmemory mcp servegoodmemory-mcpgoodmemory codex hookgoodmemory codex writebackgoodmemory claude hookgoodmemory claude writebackgoodmemory codex bootstrapgoodmemory claude bootstrapgoodmemory eval inspectgoodmemory eval tracegoodmemory eval export-caseThe public CLI contract is the package bin goodmemory. In a local Bun
consumer, invoke it as ./node_modules/.bin/goodmemory .... This repo also
keeps a repo-local script alias for development, but that alias is not part of
the installed-package contract.
Installed-package quickstart and integration guidance:
READMERepo-local developer examples:
运行方式：
bun run example:chat
bun run example:coding-agent
bun run example:ai-sdk-server
bun run example:vercel-ai
bun run example:life-coach-profile
bun run example:host-claude
bun run example:host-codex
GoodMemory also exposes a dedicated host adapter surface:
import { createGoodMemory } from "goodmemory";
import { createHostAdapter } from "goodmemory/host";
const memory = createGoodMemory({});
const adapter = createHostAdapter({
id: "codex-handoff",
hostKind: "codex",
memory,
readableArtifactTypes: ["session_memory"],
});
const result = await adapter.readArtifacts({
scope: { userId: "u-1", workspaceId: "workspace-a", sessionId: "s-1" },
includeRuntime: true,
});
Mode guidance:
file-assisted: read compiled artifacts such as MEMORY.md, user.md, session-memory/<sessionId>.md, and playbooks/*.md without writing back into canonical state.file-authoritative: available for the minimal writable subset. Today that subset is the canonical playbooks/*.md file only, and it writes back structured deltas into active validated_pattern feedback records.Writable guardrails:
*.prompt.md, *.skill.md) remain derived read-only outputsGuidance rule edits require an explicit verifyWrite approval before they are appliedappliesTo and Why can write back without the extra verification stepfile-assisted mode and inspect the compiled artifacts firstCurrent host adapter examples stay in file-assisted mode because they are the recommended default path for Claude/Codex-style integration.
Reference docs:
GoodMemory's canonical Node-first AI SDK integration is a plain Request -> Response server handler built from createGoodMemory() plus createGoodMemoryAISDK():
import { createGoodMemory } from "goodmemory";
import type { GoodMemoryStreamTextInput } from "goodmemory/ai-sdk";
import { createGoodMemoryAISDK } from "goodmemory/ai-sdk";
const memory = createGoodMemory({});
const aiSDK = createGoodMemoryAISDK({
memory,
});
type MemoryChatRequest = Pick<
GoodMemoryStreamTextInput,
"messages" | "query" | "scope" | "system"
>;
function isMemoryChatRequest(value: unknown): value is MemoryChatRequest {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return false;
}
const candidate = value as Record<string, unknown>;
const scope = candidate.scope;
return Array.isArray(candidate.messages)
&& !!scope
&& typeof scope === "object"
&& !Array.isArray(scope)
&& typeof (scope as { userId?: unknown }).userId === "string"
&& (scope as { userId: string }).userId.trim().length > 0;
}
export async function handleMemoryChat(request: Request): Promise<Response> {
const body: unknown = await request.json();
if (!isMemoryChatRequest(body)) {
return new Response(
JSON.stringify({
error: "Expected a request body with a messages array and scope.userId.",
}),
{
headers: {
"content-type": "application/json; charset=utf-8",
},
status: 400,
},
);
}
const result = aiSDK.streamText({
messages: body.messages,
query: body.query,
scope: body.scope,
system: body.system,
model: {} as never,
});
return result.toTextStreamResponse();
}
Notes:
examples/vercel-ai-chat.ts remains as the lower-level wrapper/API exampleexport async function POST(request: Request) straight to the same handler bodyscope.userId plus messages[] at the HTTP boundary before forwarding into aiSDK.streamTextModelMessage-first on the server integration pathsystem via recall() + buildContext() and soft-fails if the memory layer errorsGoodMemory 的稳定 OSS 入口是内存 API、Node-compatible 编译型包边界、Bun-backed 已安装 CLI，以及默认推荐的 file-assisted host adapter 路径。当前哪些能力已经稳定、哪些仍是内部 rollout 机制、以及现行证据该看哪里，统一收敛在 docs/GoodMemory-Current-Status-and-Evidence.md。
默认运行时现在遵循 local-first 自动解析：
storage.provider 优先./.goodmemory/memory.sqliteGOODMEMORY_EMBEDDING_* 完整配置时才自动开启 embeddings；否则保持 rules-onlysqlite-vss indexed backend；如果运行时不支持，则明确保持 durable fallback，不会假装已经加速0.1.2 当前的包边界合同是 goodmemory / goodmemory/ai-sdk / goodmemory/host 走编译型 dist/ 导出；CLI 仍然是 Bun-backed 的运行时附加面历史 phase closure 文档已经从顶层 docs 下沉到 docs/archive/quality-gates/README.md。README 不再承担按 phase 讲述构建历史的职责；如果你要看执行顺序、闭环状态或 reopen 规则，入口是 task-board/00-README.txt。
默认红绿灯：
bun test
bun run test:coverage
说明：
bun test: canonical repository suite，只扫描 tests/，与 CI 的 deterministic red/green 对齐bun run test:coverage: 在同一套 tests/ 上跑 coverage gatebun run test:all: 额外扫 tests/ 之外的 vendored / third-party test trees，只在你明确要做更宽的回归时使用评测链路支持：
命令：
bun run eval:smoke
bun run eval:fallback
bun run eval:live
bun run eval:live-memory
bun run eval:live-auto-memory
bun run eval:live-provider-memory
bun run eval:summary
含义：
eval:smoke: 最小 harness 自检，不代表产品评测结果eval:fallback: deterministic pipeline 验证，不调用真实模型，不可作为产品证据eval:live: 真实模型生成 + 真实模型 judge 的产品评测入口，使用 in-memory memory backendeval:live-memory: 真实模型生成 + 真实模型 judge 的 auto-storage 记忆评测入口；没有 GOODMEMORY_STORAGE_PROVIDER / GOODMEMORY_STORAGE_URL 时走本地 SQLite，配置 Postgres storage URL 时才走 provider-backedeval:live-auto-memory: eval:live-memory 的显式别名，适合需要强调 auto-storage 语义的脚本eval:live-provider-memory: provider-backed 产品评测入口，强制验证 Postgres + embedding + assisted extraction 的真实记忆链路；不会静默 fallback 到 SQLiteeval:summary: 汇总已有 eval 运行目录，便于审阅当前证据eval:live 必须显式配置以下环境变量，否则会直接失败：
GOODMEMORY_EVAL_PROVIDERGOODMEMORY_EVAL_BASE_URL for OpenAI-compatible gatewaysGOODMEMORY_EVAL_MODELGOODMEMORY_EVAL_API_KEYGOODMEMORY_EVAL_MAX_CONCURRENCY optional live eval parallelism capGOODMEMORY_JUDGE_PROVIDERGOODMEMORY_JUDGE_BASE_URL for OpenAI-compatible gatewaysGOODMEMORY_JUDGE_MODELGOODMEMORY_JUDGE_API_KEYeval:live-memory / eval:live-auto-memory 需要以上全部变量，另外还需要 embedding 和 assisted extractor 配置。它们不读取 GOODMEMORY_TEST_POSTGRES_URL；storage 按正常 runtime 规则解析，默认本地 SQLite：
GOODMEMORY_EMBEDDING_PROVIDERGOODMEMORY_EMBEDDING_BASE_URL for OpenAI-compatible gatewaysGOODMEMORY_EMBEDDING_MODELGOODMEMORY_EMBEDDING_API_KEYGOODMEMORY_ASSISTED_EXTRACTOR_PROVIDERGOODMEMORY_ASSISTED_EXTRACTOR_BASE_URL for OpenAI-compatible gatewaysGOODMEMORY_ASSISTED_EXTRACTOR_MODELGOODMEMORY_ASSISTED_EXTRACTOR_API_KEYeval:live-provider-memory 需要 eval:live-memory 的全部变量，另外还需要：
GOODMEMORY_TEST_POSTGRES_URL产物目录：
reports/eval/live/run-*reports/eval/live-memory/run-*reports/eval/live-provider-memory/run-*reports/eval/fallback/run-*历史 phase 专用 gate / eval 命令仍然存在，但它们已经被收口到 task board 和 quality-gate archive，而不再作为 README 的主入口。
GoodMemory v1 keeps rules-only as the supported baseline. New retrieval behavior should move through observe -> assist -> promote, and non-default promotion should only happen after an accepted/passed promotion gate with no blocking regressions plus a trusted internal promotion authorization artifact.
Operator guidance:
observe: collect isolated shadow evidence without changing the executed pathassist: allow candidate execution in controlled eval runspromote: require strategy-promotion-gate.json, a clean regression-dashboard.json, and strategy-promotion-authorization.jsonrules-only when eval evidence is incomplete, provider-backed dependencies are unavailable, or rollback conditions are present当前实现重点覆盖：
尚未在 v1 完成的内容仍以 task board 为准，入口见 task-board/00-README.txt。
FAQs
Memory layer for chat, copilot, and agent applications.
The npm package goodmemory receives a total of 399 weekly downloads. As such, goodmemory popularity was classified as not popular.
We found that goodmemory demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.