{"_id":"1memory","_rev":"2-55c6a99b265cdb1b8da6ef7055f37f25","name":"1memory","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"1memory","version":"0.0.1","license":"Apache-2.0","_id":"1memory@0.0.1","maintainers":[{"name":"nya","email":"nya@v3ritas.com"}],"homepage":"https://github.com/nya1/1memory#readme","bugs":{"url":"https://github.com/nya1/1memory/issues"},"bin":{"1memory":"dist/cli.js"},"dist":{"shasum":"79e98a7d78addcce561c33f6cb41ddc33cf4f499","tarball":"https://registry.npmjs.org/1memory/-/1memory-0.0.1.tgz","fileCount":38,"integrity":"sha512-XI3lHWJpB3bnBH0j/AsQ34PlwDSiY61DievaKovMPnMIFPKJ3tl2BrmthHVl3gbJJk+e8PPu1G90oTX3RIZi2A==","signatures":[{"sig":"MEUCICNpkOskEkEoUimarwkt/AMtFYD0qMHmUkeY7I1eeEe6AiEAyFZX7NgJd41Hi124AkoZJa8G086I8PB6h1fKysmytB4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":18563403},"type":"module","_from":"file:1memory-0.0.1.tgz","engines":{"node":">=20"},"scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","dev:mcp":"tsx src/cli.ts mcp","pretest":"node scripts/download-embedding-model.mjs","typecheck":"tsc -p tsconfig.json --noEmit","predev:mcp":"node scripts/download-embedding-model.mjs","test:watch":"vitest","dev:explore":"tsx src/cli.ts explore","setup:embeddings":"node scripts/download-embedding-model.mjs","benchmark:retrieval":"tsx benchmark/run.ts","prebenchmark:retrieval":"node scripts/download-embedding-model.mjs"},"_npmUser":{"name":"nya","email":"nya@v3ritas.com"},"_resolved":"/tmp/bdc90238b4c45ebfea499d55636b8689/1memory-0.0.1.tgz","_integrity":"sha512-XI3lHWJpB3bnBH0j/AsQ34PlwDSiY61DievaKovMPnMIFPKJ3tl2BrmthHVl3gbJJk+e8PPu1G90oTX3RIZi2A==","repository":{"url":"git+https://github.com/nya1/1memory.git","type":"git"},"_npmVersion":"11.9.0","description":"A local memory layer for coding agents.","directories":{},"_nodeVersion":"25.6.1","dependencies":{"ink":"5","zod":"^3.24.2","react":"18","nanoid":"^5.1.5","ink-text-input":"6","@lancedb/lancedb":"^0.21.0","@huggingface/transformers":"^3.5.2","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.3","vitest":"^3.1.1","typescript":"^5.8.3","@types/node":"^22.14.0","@types/react":"18"},"_npmOperationalInternal":{"tmp":"tmp/1memory_0.0.1_1777323638745_0.8985387363942912","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"1memory","version":"0.1.0","license":"Apache-2.0","type":"module","packageManager":"pnpm@9.15.9","bin":{"1memory":"dist/cli.js"},"repository":{"type":"git","url":"git+https://github.com/nya1/1memory.git"},"scripts":{"build":"tsc -p tsconfig.json","prepublishOnly":"tsc -p tsconfig.json && node scripts/download-embedding-model.mjs","setup:embeddings":"node scripts/download-embedding-model.mjs","predev:mcp":"node scripts/download-embedding-model.mjs","pretest":"node scripts/download-embedding-model.mjs","prebenchmark:retrieval":"node scripts/download-embedding-model.mjs","dev:mcp":"tsx src/cli.ts mcp","dev:explore":"tsx src/cli.ts explore","test":"vitest run","test:watch":"vitest","typecheck":"tsc -p tsconfig.json --noEmit","benchmark:retrieval":"tsx benchmark/run.ts"},"engines":{"node":">=20"},"dependencies":{"@huggingface/transformers":"^3.5.2","@lancedb/lancedb":"^0.21.0","@modelcontextprotocol/sdk":"^1.12.0","ink":"5","ink-text-input":"6","nanoid":"^5.1.5","react":"18","zod":"^3.24.2"},"devDependencies":{"@types/node":"^22.14.0","@types/react":"18","tsx":"^4.19.3","typescript":"^5.8.3","vitest":"^3.1.1"},"gitHead":"f4d777bdc3f8189f4f625bbfbd9cbe2a2029857c","_id":"1memory@0.1.0","description":"A local memory layer for coding agents.","bugs":{"url":"https://github.com/nya1/1memory/issues"},"homepage":"https://github.com/nya1/1memory#readme","_nodeVersion":"22.14.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-Z+GnHXbbrqNy0QHgRR+dQtrM4xBImBaYXs26ZU4nGs8RH3/mLwwWNCwzLBrd41Znp/umV7zdeBJtuaGagZvmKg==","shasum":"38be0165a43095e66e2d5c3ca0e875bfe45d79c8","tarball":"https://registry.npmjs.org/1memory/-/1memory-0.1.0.tgz","fileCount":37,"unpackedSize":18562654,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/1memory@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDJQJQ7REOiIPJeZxzQ3X0eP94aD42Z9yDe10xrMvty0QIgIrfaJBhYeMRdN+vQMYqIrVMzAvTHSp7ZsKYwyrIMx9I="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:4a926d8b-f198-4789-949f-b181f919525e"}},"directories":{},"maintainers":[{"name":"nya","email":"nya@v3ritas.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/1memory_0.1.0_1777390263843_0.6047030758493048"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-27T21:00:38.744Z","modified":"2026-04-28T15:31:04.678Z","0.0.1":"2026-04-27T21:00:39.341Z","0.1.0":"2026-04-28T15:31:04.322Z"},"bugs":{"url":"https://github.com/nya1/1memory/issues"},"license":"Apache-2.0","homepage":"https://github.com/nya1/1memory#readme","repository":{"type":"git","url":"git+https://github.com/nya1/1memory.git"},"description":"A local memory layer for coding agents.","maintainers":[{"name":"nya","email":"nya@v3ritas.com"}],"readme":"# 1memory\n\nA local memory layer for coding agents.\n\n1memory runs as an MCP server on your machine. Agents can write down what matters, recall it later, and carry useful context across sessions without a hosted service. Semantic recall uses vector search with a local ONNX embedding model (`paraphrase-MiniLM-L3-v2`) published on npm with the package, so it is always available offline.\n\n**Synthetic recall benchmark:** ~83% recall@1\n\nIt is built for local-first agent work:\n\n- No login\n- No Docker\n- No external database\n- No hosted embedding API\n- No background daemon\n\n```json\n{\n  \"mcpServers\": {\n    \"1memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"1memory\", \"mcp\"]\n    }\n  }\n}\n```\n\n## The Idea\n\nAgents are good inside one context window. They are weaker across time.\n\nThey forget what was confirmed. They forget what was ruled out. They forget the handoff from the last session. They may ask you to repeat facts the previous agent already learned.\n\n1memory gives agents a small local memory system:\n\n- write memories explicitly\n- recall memories with citations\n- start sessions with compact context\n- end sessions with a handoff\n- inspect stored memories when something looks wrong\n\nThe goal is not to replace files, docs, or git history. The goal is to preserve the working memory that normally disappears when the chat ends.\n\n## Memory Types\n\n1memory stores four kinds of memory:\n\n- **Facts:** stable information that should be available later.\n  Example: \"The retry bug only reproduces when provider retries overlap with the replay job.\"\n\n- **Events:** things that happened at a point in time.\n  Example: \"On Monday, the investigation ruled out timezone parsing.\"\n\n- **Instructions:** guidance the agent should follow in future sessions.\n  Example: \"When touching the installer, run the MCP integration tests before reporting completion.\"\n\n- **Tasks:** open work and handoff items.\n  Example: \"Verify whether async ingest resumes after MCP restart.\"\n\nThis keeps memory structured enough for agents to use, but simple enough to inspect.\n\n## Why Local\n\nMemory is only useful if you can trust where it lives.\n\n1memory stores data locally by default:\n\n```text\n~/.1memory/\n```\n\nUnder the hood it uses LanceDB as an embedded local store. The MCP server is started by your editor or agent client as a stdio process. There is no service to run, no account to create, and no remote database to provision.\n\nRetrieval works locally too. Lexical, metadata, and vector search run on your machine. Vector search uses the same local ONNX embedding model (`paraphrase-MiniLM-L3-v2`) shipped on npm with 1memory, so semantic recall does not require a separate download or an embedding API.\n\n## Quick Start\n\nRequires Node.js 20 or newer.\n\nAdd 1memory to an MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"1memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"1memory\", \"mcp\"]\n    }\n  }\n}\n```\n\nFor a terminal UI to browse and search local memories:\n\n```bash\nnpx -y 1memory explore\n```\n\n## Client Install\n\n1memory can generate workspace-scoped MCP config for supported clients:\n\n```bash\nnpx -y 1memory mcp install cursor\nnpx -y 1memory mcp install claude-code\nnpx -y 1memory mcp install claude-desktop\n```\n\nPreview the generated files:\n\n```bash\nnpx -y 1memory mcp install cursor --dry-run\n```\n\nChoose scope:\n\n```bash\nnpx -y 1memory mcp install cursor --scope=workspace\n```\n\nCurrent 0.1 installer support focuses on workspace config. User-scope install planning is recognized, but workspace artifacts are used today.\n\n## MCP Surface\n\nThe 0.1 server exposes the core local memory loop:\n\n```text\nmemory_capabilities\nmemory_health\nmemory_explain_setup\nmemory_profiles_list\nmemory_profile_current\nmemory_profile_select\nmemory_session_start\nmemory_context\nmemory_recall\nmemory_remember\nmemory_get\nmemory_list\nmemory_session_end\nmemory_ingest_status\n```\n\nA typical session:\n\n1. The agent starts a session and asks 1memory for compact context.\n2. During work, the agent recalls facts, events, instructions, or tasks.\n3. When something worth keeping is learned, the agent writes a memory.\n4. At the end, the agent records a handoff.\n5. A later session can pick up from the stored memory instead of starting cold.\n\n## What 0.1 Includes\n\n1memory 0.1 is focused on making local memory useful.\n\nIncluded:\n\n- MCP stdio server\n- Local profile resolution\n- Local LanceDB persistence\n- Explicit memory writes\n- Memory get, list, and recall\n- Session start and session end records\n- Compact context blocks\n- Lexical, metadata, and vector retrieval with the npm-shipped local embedding model\n- Request IDs, warnings, and predictable response envelopes\n- Startup migrations and schema tracking\n- Local write mutex for safer concurrent access\n- Audit events for selected reads and writes\n- Cursor, Claude Code, Claude Desktop, and generic MCP config generation\n\nNot in the 0.1 core:\n\n- Hosted sync\n- Team accounts\n- Remote admin UI\n- `doctor`\n- export commands\n- advanced correction tools such as supersede, forget, timeline, verify, and feedback\n\n## Architecture\n\n```text\nMCP client\n  -> 1memory mcp\n  -> profile resolver\n  -> memory, session, and recall services\n  -> local LanceDB\n```\n\nThe memory record is the source of truth. Recall results, context blocks, and future exports are derived from stored records rather than becoming separate hidden state.\n\n## Development\n\n\n```bash\npnpm install\n```\n\nBuild:\n\n```bash\npnpm run build\n```\n\nTypecheck:\n\n```bash\npnpm run typecheck\n```\n\nRun tests:\n\n```bash\npnpm test\n```\n\nRun from source:\n\n```bash\npnpm run dev:mcp\n```\n\n## Benchmark\n\nRetrieval benchmark (synthetic corpus in `benchmark/scenarios.json`; requires the local embedding model, same as tests). Metrics vary by machine and load.\n\n```bash\npnpm run benchmark:retrieval\n```\n\nExample output:\n\n```text\n1memory retrieval benchmark (synthetic corpus, local embeddings)\ncases=6 queries=18 limit=8\nrecall@1     83.3%\nrecall@8 100.0%\nMRR          0.903\nmean latency 24.84 ms\n  - handoff-retry-overlap: @1 100% @8 100% mrr 1.00 (9 mem, 3 q)\n  - mcp-stdio-instruction: @1 67% @8 100% mrr 0.83 (7 mem, 3 q)\n  - ingest-resume-semantics: @1 67% @8 100% mrr 0.75 (8 mem, 3 q)\n  - prefs-among-noise: @1 100% @8 100% mrr 1.00 (8 mem, 3 q)\n  - timezone-ruled-out: @1 100% @8 100% mrr 1.00 (6 mem, 3 q)\n  - dense-shared-vocabulary: @1 67% @8 100% mrr 0.83 (8 mem, 3 q)\n```\n\nUse `pnpm run benchmark:retrieval -- --json` for machine-readable results.\n\n## CI and releases\n\nCI runs on pushes and pull requests to `main`. Release steps, npm OIDC trusted publishing, and tagging are documented in [`RELEASE.md`](RELEASE.md).\n\n## License\n\nApache-2.0. See `LICENSE`.\n","readmeFilename":"README.md"}