{"_id":"@aifcoding/memory-core","_rev":"3-0b6f55b06b6ade7aa391ec817721b3b3","name":"@aifcoding/memory-core","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@aifcoding/memory-core","version":"0.1.0","keywords":["ai","memory","core","sqlite","retrieval"],"license":"MIT","_id":"@aifcoding/memory-core@0.1.0","maintainers":[{"name":"aifcodinggaopser","email":"shaoecnu@gmail.com"}],"homepage":"https://github.com/aifcoding/opencode-memory#readme","bugs":{"url":"https://github.com/aifcoding/opencode-memory/issues"},"dist":{"shasum":"d411120347b3cf902972e84709a577da2c710c5a","tarball":"https://registry.npmjs.org/@aifcoding/memory-core/-/memory-core-0.1.0.tgz","fileCount":17,"integrity":"sha512-kPgpI9CHqHx60kBiokWRWJUWV1YunkoxtjSDHJVkm1CDWozX6o01dyaU/BwASuUNVxY7TH0ff9nk1vutOWl24g==","signatures":[{"sig":"MEQCIAdxc8JaNBl+bpOLq6I9LiVHpWpnRnnLaXdxj7re6M01AiB7Ek/b3K6lPcmwVSzuhq3F1xvuMQlKy3n8Wwz2e6JwHQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":54163},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./sqlite":{"types":"./dist/sqlite/index.d.ts","import":"./dist/sqlite/index.js"}},"gitHead":"95fbe47189fc2d73a301609f384214660ab6f82b","scripts":{"test":"bun test tests","build":"rm -rf dist && bun build src/index.ts src/sqlite/index.ts --outdir dist --target bun --external jieba-wasm && tsc -p tsconfig.build.json --declaration --emitDeclarationOnly --noEmit false --outDir dist","typecheck":"tsc --noEmit","prepublishOnly":"bun run typecheck && bun test && bun run build"},"_npmUser":{"name":"aifcodinggaopser","email":"shaoecnu@gmail.com"},"repository":{"url":"git+https://github.com/aifcoding/opencode-memory.git","type":"git"},"_npmVersion":"11.18.0","description":"Framework-independent memory storage primitives","directories":{},"_nodeVersion":"26.6.0","dependencies":{"jieba-wasm":"^2.4.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.4.2","typescript":"^7.0.2"},"_npmOperationalInternal":{"tmp":"tmp/memory-core_0.1.0_1789119317826_0.8066935526659005","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aifcoding/memory-core","version":"0.2.0","keywords":["ai","memory","core","sqlite","retrieval"],"license":"MIT","_id":"@aifcoding/memory-core@0.2.0","maintainers":[{"name":"aifcodinggaopser","email":"shaoecnu@gmail.com"}],"homepage":"https://github.com/aifcoding/opencode-memory#readme","bugs":{"url":"https://github.com/aifcoding/opencode-memory/issues"},"dist":{"shasum":"a216d59ec842dba5d52717b0dfe843cf4eeb13ae","tarball":"https://registry.npmjs.org/@aifcoding/memory-core/-/memory-core-0.2.0.tgz","fileCount":19,"integrity":"sha512-0CeQGw6j7zDWna/y40dAJxdLB51GRdCoIEuOvqg40N/EFUG8luxp6ivKHt33Vwpuwe5OxjLES7HakJLsBn9Mpg==","signatures":[{"sig":"MEYCIQCXSmwQcw1/pyTYrKgFRrllGH1jQuXfruxIIz15y5YdNwIhAPCkMBGUHgt7Ixdd/UNSj1yz43JfEch60QzcVsSgxnY3","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIQDm4wwnxw6yjHzWKJMqTOz0JBNQMnK4AYADLXoJI/hUGQIgF8HeyxE1CVmiWgIpRtR7cnaeT5PLKr7eXhQgjK+ZKm0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76893},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./sqlite":{"types":"./dist/sqlite/index.d.ts","import":"./dist/sqlite/index.js"}},"gitHead":"050533d60d446d6f1d011ae5a5c23ced54ef3da9","scripts":{"test":"bun test tests","build":"rm -rf dist && bun build src/index.ts src/sqlite/index.ts --outdir dist --target bun --external jieba-wasm && tsc -p tsconfig.build.json --declaration --emitDeclarationOnly --noEmit false --outDir dist","typecheck":"tsc --noEmit","prepublishOnly":"bun run typecheck && bun test && bun run build"},"_npmUser":{"name":"aifcodinggaopser","email":"shaoecnu@gmail.com"},"repository":{"url":"git+https://github.com/aifcoding/opencode-memory.git","type":"git"},"_npmVersion":"11.18.0","description":"Framework-independent memory storage primitives","directories":{},"_nodeVersion":"26.6.0","dependencies":{"jieba-wasm":"^2.4.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.4.2","typescript":"^7.0.2"},"_npmOperationalInternal":{"tmp":"tmp/memory-core_0.2.0_1789367061749_0.6453310604228149","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"_id":"@aifcoding/memory-core@0.3.0","bugs":{"url":"https://github.com/aifcoding/opencode-memory/issues"},"dist":{"shasum":"0a1b7651e9db307082931a0611376149a7335c70","tarball":"https://registry.npmjs.org/@aifcoding/memory-core/-/memory-core-0.3.0.tgz","fileCount":21,"integrity":"sha512-dhus6Qc8GYynwauLp98Z+va0K09OLCsgWJCqRCH8HjZ3RGz4Kob+JvfJocijBGAKbrA6RQTonAfGAGBEg1BeDw==","signatures":[{"sig":"MEUCIAkBkAk4ZbdZQyyb9IMAV/Jh9qJKJv+aXhHJpBWzfNX7AiEAzLhVW/mkklRXuJBM4VV6KeekjneUxbZ4OR6XPLN9E1I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICg7lPv73gcUO0QKcfq7qh9st7+b4RRnSnagtKpC1F0xAiEApBrC/jDv/tRnKE3BJ8EQWMROXIsHhzsmghVaTNPlq4Q="}],"unpackedSize":105705},"name":"@aifcoding/memory-core","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./sqlite":{"types":"./dist/sqlite/index.d.ts","import":"./dist/sqlite/index.js"}},"gitHead":"830e955f4b67a70dae8d19757818cd0658bfaae7","license":"MIT","scripts":{"test":"bun test tests","build":"rm -rf dist && bun build src/index.ts src/sqlite/index.ts --outdir dist --target bun --external jieba-wasm && tsc -p tsconfig.build.json --declaration --emitDeclarationOnly --noEmit false --outDir dist","typecheck":"tsc --noEmit","prepublishOnly":"bun run typecheck && bun test && bun run build"},"version":"0.3.0","_npmUser":{"name":"aifcodinggaopser","email":"shaoecnu@gmail.com"},"homepage":"https://github.com/aifcoding/opencode-memory#readme","keywords":["ai","memory","core","sqlite","retrieval"],"repository":{"url":"git+https://github.com/aifcoding/opencode-memory.git","type":"git"},"_npmVersion":"11.18.0","description":"Framework-independent memory storage primitives","directories":{},"maintainers":[{"name":"aifcodinggaopser","email":"shaoecnu@gmail.com"}],"_nodeVersion":"26.6.0","dependencies":{"jieba-wasm":"^2.4.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"^1.4.2","typescript":"^7.0.2"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/memory-core_0.3.0_1789544771859_0.2785070126976843"}}},"time":{"created":"2026-09-11T09:35:17.572Z","modified":"2026-09-16T07:46:12.099Z","0.1.0":"2026-09-11T09:35:17.964Z","0.2.0":"2026-09-14T06:24:21.831Z","0.3.0":"2026-09-16T07:46:11.947Z"},"bugs":{"url":"https://github.com/aifcoding/opencode-memory/issues"},"license":"MIT","homepage":"https://github.com/aifcoding/opencode-memory#readme","keywords":["ai","memory","core","sqlite","retrieval"],"repository":{"url":"git+https://github.com/aifcoding/opencode-memory.git","type":"git"},"description":"Framework-independent memory storage primitives","maintainers":[{"name":"aifcodinggaopser","email":"shaoecnu@gmail.com"}],"readme":"# @aifcoding/memory-core\n\n[简体中文](#中文) | [English](#english)\n\n## 中文\n\n框架无关的本地 AI 记忆内核，提供异步 `MemoryManager`、检索、Pin 和结构化领域 API。\n\n### 安装与入口\n\n```bash\nbun add @aifcoding/memory-core\n```\n\n根入口 `@aifcoding/memory-core` 提供类型、Manager 和默认 Tokenizer，不加载 `bun:sqlite`。SQLite 实现从 `@aifcoding/memory-core/sqlite` 导入：\n\n```ts\nimport { createSqliteMemoryManager } from '@aifcoding/memory-core/sqlite';\nconst manager = createSqliteMemoryManager({ dbPath: '/tmp/memory.db' });\n```\n\n`/sqlite` 使用 `bun:sqlite`，因此要求 Bun 运行时。\n\n### MemoryManager API\n\n| 能力 | 方法 |\n|---|---|\n| 长期记忆 | `storeMemory`、`recallMemories`、`listMemories`、`readMemory`、`forgetMemory` |\n| Pin | `pinMemory`、`unpinMemory`、`listPinnedMemories`、`getPinnedContext` |\n| 情景摘要 | `archiveSummary`、`recallSummaries` |\n| Context KV | `setContextValue`、`getContextValue`、`listContextValues`、`deleteContextValue` |\n| 生命周期 | `close` |\n\n方法使用对象参数并返回 Promise。`MemoryManagerOptions` 支持 `defaultScope`（默认 `global/default`）、`pinQuota`（默认 8000 字符）、`defaultOrigin` 和 `defaultTrust`。\n\n`PinResult` 会区分 `pinned`、`quota_exceeded`、`summary_required`、`trust_denied`、`not_found` 和 `deleted`。`getPinnedContext` 返回 `{ entries, text, size }`。\n\n### 分层 Recall\n\n`recallMemories` 统一返回投影结果，默认 `summary`（标题+摘要）；只有显式 `projection: 'full'` 或 `readMemory/readReference` 才返回完整正文。没有已保存摘要时，summary 回退正文前 200 字符（`summarySource=content_preview`，不改库）。\n\n字符预算（可部分覆盖，其余用默认值）：\n\n```ts\n{\n  maxCharacters: 3000,         // Detail 标题/摘要预算（1..20000）\n  preferSummary: true,         // full 放不下时降级 summary\n  maxOverflowItems: 10,        // 溢出导航最多条数（0..20，0=关闭）\n  maxOverflowCharacters: 1500, // 溢出导航字符预算（0..10000）\n}\n```\n\n结果：`memories`（预算内 Detail）+ `overflow`（预算外 L0 导航：id/ref/title/trust/score）+ `consideredCount/usedCharacters/overflowUsedCharacters/truncated/degradedCount/omittedCount`。score 是本次 FTS5/BM25 相对相关度，不可跨查询比较。字符数按 UTF-16 `string.length`，不等于 Token。\n\n### Memory Ref\n\n`memory://local/memories/{id}` / `summaries/{encoded-id}` / `candidates/{id}`。`memoryRef/summaryRef/candidateRef` 生成、`parseMemoryReference` 严格解析。只保证同一数据库内稳定。\n\n### readReference\n\n`readReference({ref, scope})` → `found/not_found/deleted/unsupported`。Memory/Candidate 走 Scope 校验；Summary 当前无 Scope、按全局唯一 ID 读；MCP 不暴露通用 readReference。\n\n### Scope 与 contextKey\n\n长期知识使用显式 `ScopeRef`（`scope` + `scopeKey`），或使用 `defaultScope`；Context KV 必须显式提供 `contextKey`，Core 不会推断它。\n\n### 自定义 Tokenizer\n\n默认使用 `jieba-wasm`；可注入实现 `Tokenizer` 接口的自定义分词器：\n\n```ts\nimport type { Tokenizer } from '@aifcoding/memory-core';\nimport { createSqliteMemoryManager } from '@aifcoding/memory-core/sqlite';\n\nconst englishTokenizer: Tokenizer = {\n  tokenize: (text) => text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join(' '),\n};\nconst manager = createSqliteMemoryManager({ dbPath: '/tmp/memory.db', tokenizer: englishTokenizer });\n```\n\nTokenizer 是数据库索引格式的一部分；已有数据库必须使用兼容 Tokenizer。当前没有自动索引重建接口，如需更换，请导出数据并用新数据库重新导入。\n\n### MemoryStore 与错误\n\n`MemoryStore` 是同步的低层扩展端口，负责存储原语、检索和事务一致性；`MemoryManager` 是异步公共边界，负责校验、默认值和结构化结果。`MemoryValidationError` 表示输入无效，`DuplicateMemoryError` 表示同一作用域中存在重复的未删除内容。\n\n## English\n\n`@aifcoding/memory-core` is a framework-independent local AI memory core. It provides an asynchronous `MemoryManager`, retrieval, Pin operations, and structured domain results.\n\n### Installation and entry points\n\n```bash\nbun add @aifcoding/memory-core\n```\n\nThe root entry provides types, `MemoryManager`, and the default tokenizer without loading `bun:sqlite`. Import the SQLite factory from `@aifcoding/memory-core/sqlite`; this subpath requires Bun.\n\n### MemoryManager API\n\nThe main methods are `storeMemory`, `recallMemories`, `listMemories`, `readMemory`, `forgetMemory`, `pinMemory`, `unpinMemory`, `listPinnedMemories`, `getPinnedContext`, `archiveSummary`, `recallSummaries`, `setContextValue`, `getContextValue`, `listContextValues`, `deleteContextValue`, and `close`. All methods take object arguments and return Promises.\n\n`MemoryManagerOptions` accepts `defaultScope` (default `global/default`), `pinQuota` (default 8000 characters), `defaultOrigin`, and `defaultTrust`. Long-term memories use an explicit `ScopeRef` or `defaultScope`; Context KV requires an explicit `contextKey`, which Core never infers.\n\nPin results include `pinned`, `quota_exceeded`, `summary_required`, `trust_denied`, `not_found`, and `deleted`. `getPinnedContext` returns `{ entries, text, size }`. `MemoryStore` is the synchronous low-level extension port; Manager is the asynchronous public boundary. `MemoryValidationError` reports invalid input and `DuplicateMemoryError` reports duplicate active content.\n\n### Layered recall\n\n`recallMemories` returns one unified projected result and defaults to the `summary` projection. Use `projection: \"full\"` or `readMemory` for full content. Default budget: `{ maxCharacters: 3000, preferSummary: true, maxOverflowItems: 10, maxOverflowCharacters: 1500 }`. Overflow entries contain `id/ref/title/trust/score`; scores are query-relative BM25 and must not be compared across queries. Character budgets use `string.length`, not model tokens.\n\n### Memory references\n\n`memory://local/memories/{id}` etc.; `parseMemoryReference` for strict parsing; `readReference` for resolution. Stable only within the same database. Summaries have no Scope, so MCP does not expose a generic reference tool.\n\n### Capture API\n\nThe capture API consists of `beginCapture`, `completeCapture`, `failCapture`, `listMemoryCandidates`, `readMemoryCandidate`, and `reviewMemoryCandidate`. Candidates are isolated, default to `origin=agent`, `trust=low`, and `pending`, and never participate in recall or Pin before approval.\n\n### Custom Tokenizer\n\nThe default tokenizer uses `jieba-wasm`. Inject any implementation of the `Tokenizer` interface through the SQLite factory:\n\n```ts\nimport { createSqliteMemoryManager } from '@aifcoding/memory-core/sqlite';\nimport type { Tokenizer } from '@aifcoding/memory-core';\n\nconst tokenizer: Tokenizer = {\n  tokenize: (text) => text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join(' '),\n};\nconst manager = createSqliteMemoryManager({ dbPath: '/tmp/memory.db', tokenizer });\n```\n\nTokenizers are part of the database index format. Existing databases require a compatible tokenizer; automatic index rebuilding is not provided. Export and re-import data into a new database when changing one.\n","readmeFilename":"README.md"}