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",
});
GoodMemory 0.1.1 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.1
Bun install:
bun add goodmemory@0.1.1
Tarball verification for release rehearsal before publish:
npm install ./goodmemory-0.1.1.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.1 自带一个 Bun-backed、只读的已安装 CLI。包里的 goodmemory bin 现在可以在 Node 包安装场景下安全暴露；真正执行命令时会委托给 Bun。显式 --storage-provider / --storage-url 优先；不显式指定时，会优先尝试可用的 Postgres 目标，否则在 Bun 运行时回落到当前工作目录下的 sqlite：./.goodmemory/memory.sqlite。根命令只会读取已有存储；如果最终解析到的本地 sqlite 不存在，CLI 会报错而不会隐式创建本地数据库。唯一的策略诊断例外是 trace --ignore-memory：它会把 recall 视为空集并直接跳过存储解析。
./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 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 inspectgoodmemory tracegoodmemory export-memorygoodmemory statsgoodmemory 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: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.1 当前的包边界合同是 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 118 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.