{"_id":"longmemory","name":"longmemory","dist-tags":{"latest":"1.3.3"},"versions":{"1.3.3":{"name":"longmemory","version":"1.3.3","author":{"name":"caviraoss"},"bin":{"lom":"bin/lom.js","longmemory":"bin/lom.js"},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"dev":"nodemon src/server/index.ts","format":"prettier --write \"src/**/*.ts\" \"test/**/*.ts\"","build":"tsc -p tsconfig.json","start":"node dist/server/index.js","migrate":"tsx src/migrate.ts"},"dependencies":{"@aws-sdk/client-bedrock-runtime":"^3.932.0","@azure/msal-node":"^2.0.0","@modelcontextprotocol/sdk":"^1.22.0","@notionhq/client":"^2.2.0","@octokit/rest":"^21.0.0","cheerio":"^1.0.0","dotenv":"^16.6.1","fluent-ffmpeg":"^2.1.3","googleapis":"^140.0.0","ioredis":"^5.8.2","mammoth":"^1.11.0","openai":"^4.73.0","pdf-parse":"^2.4.5","pg":"^8.16.3","sqlite3":"^5.1.7","turndown":"^7.2.2","ws":"^8.18.3","zod":"^3.25.76"},"devDependencies":{"@types/cheerio":"^0.22.35","@types/fluent-ffmpeg":"^2.1.26","@types/node":"^20.19.25","@types/pg":"^8.15.6","prettier":"^3.6.2","tsx":"^4.20.6","typescript":"^5.9.3"},"allowScripts":{"esbuild@0.28.2":true,"sqlite3@5.1.7":true},"_id":"longmemory@1.3.3","description":"> **real long-term memory for ai agents. not rag. not a vector db. self-hosted.**","_nodeVersion":"24.17.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-c9eeiHWLzOkUJq5t6uaP352cjhMv/nl3JlBhzXDS90kBBmb1r8wPnpUxI5N4+Tlk43FiCCnf/xGJrCu4PzPB3w==","shasum":"89643afa0706039ecd384d2875cac5759af4d557","tarball":"https://registry.npmjs.org/longmemory/-/longmemory-1.3.3.tgz","fileCount":125,"unpackedSize":864425,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBuNcpPX6LevLrK7hOKMRsJKQoa9lWAeSPWY5zgmyRnQAiEAy7+GXWeE5L16SS42XcDQiCCv38Gve5V4TNTCv8xMcds="}]},"_npmUser":{"name":"recabasic","email":"recabasic@gmail.com"},"directories":{},"maintainers":[{"name":"recabasic","email":"recabasic@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/longmemory_1.3.3_1788197493113_0.8121129925348682"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T17:31:33.043Z","1.3.3":"2026-08-31T17:31:33.341Z","modified":"2026-08-31T17:31:33.564Z"},"maintainers":[{"name":"recabasic","email":"recabasic@gmail.com"}],"description":"> **real long-term memory for ai agents. not rag. not a vector db. self-hosted.**","author":{"name":"caviraoss"},"readme":"# longmemory javascript sdk\n\n> **real long-term memory for ai agents. not rag. not a vector db. self-hosted.**\n\n[![npm version](https://img.shields.io/npm/v/longmemory-js.svg)](https://www.npmjs.com/package/longmemory-js)\n[![license](https://img.shields.io/github/license/CaviraOSS/LongMemory)](https://github.com/CaviraOSS/LongMemory/blob/main/LICENSE)\n[![discord](https://img.shields.io/discord/1300368230320697404?label=Discord)](https://discord.gg/P7HaRayqTh)\n\nlongmemory is a **cognitive memory engine** for llms and agents.\n\n- 🧠 real long-term memory (not just embeddings in a table)\n- 💾 self-hosted, local-first (sqlite / postgres)\n- 🧩 integrations: mcp, claude desktop, cursor, windsurf\n- 📥 sources: github, notion, google drive, onedrive, web crawler\n- 🔍 explainable traces (see *why* something was recalled)\n\nyour model stays stateless. **your app stops being amnesiac.**\n\n---\n\n## quick start\n\n```bash\nnpm install longmemory\n```\n\n```typescript\nimport { Memory } from \"longmemory\"\n\nconst mem = new Memory()\nawait mem.add(\"user likes spicy food\", { user_id: \"u1\" })\nconst results = await mem.search(\"food?\", { user_id: \"u1\" })\n```\n\ndrop this into:\n\n- node backends\n- clis\n- local tools\n- anything that needs durable memory without running a separate service\n\n**that's it.** you're now running a fully local cognitive memory engine 🎉\n\n---\n\n## 📥 sources (connectors)\n\ningest data from external sources directly into memory:\n\n```typescript\nconst github = await mem.source(\"github\")\nawait github.connect({ token: \"ghp_...\" })\nawait github.ingest_all({ repo: \"owner/repo\" })\n```\n\navailable sources: `github`, `notion`, `google_drive`, `google_sheets`, `google_slides`, `onedrive`, `web_crawler`\n\n---\n\n## features\n\n✅ **local-first** - runs entirely on your machine, zero external dependencies  \n✅ **multi-sector memory** - episodic, semantic, procedural, emotional, reflective  \n✅ **temporal knowledge graph** - time-aware facts with validity periods  \n✅ **memory decay** - adaptive forgetting with sector-specific rates  \n✅ **waypoint graph** - associative recall paths for better retrieval  \n✅ **explainable traces** - see exactly why memories were recalled  \n✅ **zero config** - works out of the box with sensible defaults  \n\n---\n\n## cognitive sectors\n\nlongmemory automatically classifies content into 5 cognitive sectors:\n\n| sector | description | examples | decay rate |\n|--------|-------------|----------|------------|\n| **episodic** | time-bound events & experiences | \"yesterday i attended a conference\" | medium |\n| **semantic** | timeless facts & knowledge | \"paris is the capital of france\" | very low |\n| **procedural** | skills, procedures, how-tos | \"to deploy: build, test, push\" | low |\n| **emotional** | feelings, sentiment, mood | \"i'm excited about this project!\" | high |\n| **reflective** | meta-cognition, insights | \"i learn best through practice\" | very low |\n\n---\n\n## configuration\n\n### environment variables\n\n```bash\n# database\nLM_DB_PATH=./data/om.db              # sqlite file path (default: ./data/longmemory.sqlite)\nLM_DB_URL=sqlite://:memory:          # or use in-memory db\n\n# embeddings\nLM_EMBEDDINGS=ollama                 # synthetic | openai | gemini | ollama\nLM_OLLAMA_URL=http://localhost:11434\nLM_OLLAMA_MODEL=embeddinggemma       # or nomic-embed-text, mxbai-embed-large\n\n# openai\nOPENAI_API_KEY=sk-...\nLM_OPENAI_MODEL=text-embedding-3-small\n\n# gemini\nGEMINI_API_KEY=AIza...\n\n# performance tier\nLM_TIER=deep                         # fast | smart | deep | hybrid\nLM_VEC_DIM=768                       # vector dimension (must match model)\n\n# metadata backend (optional)\nLM_METADATA_BACKEND=postgres         # sqlite (default) | postgres\nLM_PG_HOST=localhost\nLM_PG_PORT=5432\nLM_PG_DB=longmemory\nLM_PG_USER=postgres\nLM_PG_PASSWORD=...\n\n# vector backend (optional)\nLM_VECTOR_BACKEND=valkey             # default uses metadata backend\nLM_VALKEY_URL=redis://localhost:6379\n```\n\n### programmatic usage\n\n```typescript\nimport { Memory } from 'longmemory-js';\n\nconst mem = new Memory('user-123');  // optional user_id\n\n// add memories\nawait mem.add(\n    \"user prefers dark mode\",\n    {\n        tags: [\"preference\", \"ui\"],\n        created_at: Date.now()\n    }\n);\n\n// search\nconst results = await mem.search(\"user settings\", {\n    user_id: \"user-123\",\n    limit: 10,\n    sectors: [\"semantic\", \"procedural\"]\n});\n\n// get by id\nconst memory = await mem.get(\"uuid-here\");\n\n// wipe all data (useful for testing)\nawait mem.wipe();\n```\n\n---\n\n## performance tiers\n\n- `fast` - synthetic embeddings (no api calls), instant\n- `smart` - hybrid semantic + synthetic for balanced speed/accuracy\n- `deep` - pure semantic embeddings for maximum accuracy\n- `hybrid` - adaptive based on query complexity\n\n---\n\n## mcp server\n\nlongmemory-js includes an mcp server for integration with claude desktop, cursor, windsurf, and other mcp clients:\n\n```bash\nnpx longmemory-js serve --port 3000\n```\n\n### claude desktop / cursor / windsurf\n\n```json\n{\n  \"mcpServers\": {\n    \"longmemory\": {\n      \"command\": \"npx\",\n      \"args\": [\"longmemory-js\", \"serve\"]\n    }\n  }\n}\n```\n\navailable mcp tools:\n\n- `longmemory_query` - search memories\n- `longmemory_store` - add new memories\n- `longmemory_list` - list all memories\n- `longmemory_get` - get memory by id\n- `longmemory_reinforce` - reinforce a memory\n\n---\n\n## examples\n\n```typescript\n// multi-user support\nconst mem = new Memory();\nawait mem.add(\"alice likes python\", { user_id: \"alice\" });\nawait mem.add(\"bob likes rust\", { user_id: \"bob\" });\n\nconst alicePrefs = await mem.search(\"what does alice like?\", { user_id: \"alice\" });\n// returns python results only\n\n// temporal filtering\nconst recent = await mem.search(\"user activity\", {\n    startTime: Date.now() - 86400000,  // last 24 hours\n    endTime: Date.now()\n});\n\n// sector-specific queries\nconst facts = await mem.search(\"company info\", { sectors: [\"semantic\"] });\nconst howtos = await mem.search(\"deployment\", { sectors: [\"procedural\"] });\n```\n\n---\n\n## api reference\n\n### `new Memory(user_id?: string)`\n\ncreate a new memory instance with optional default user_id.\n\n### `async add(content: string, metadata?: object): Promise<hsg_mem>`\n\nstore a new memory.\n\n**parameters:**\n- `content` - text content to store\n- `metadata` - optional metadata object:\n  - `user_id` - user identifier\n  - `tags` - array of tag strings\n  - `created_at` - timestamp\n  - any other custom fields\n\n**returns:** memory object with `id`, `primary_sector`, `sectors`\n\n### `async search(query: string, options?: object): Promise<hsg_q_result[]>`\n\nsearch for relevant memories.\n\n**parameters:**\n- `query` - search text\n- `options`:\n  - `user_id` - filter by user\n  - `limit` - max results (default: 10)\n  - `sectors` - array of sectors to search\n  - `startTime` - filter memories after this timestamp\n  - `endTime` - filter memories before this timestamp\n\n**returns:** array of memory results with `id`, `content`, `score`, `sectors`, `salience`, `tags`, `meta`\n\n### `async get(id: string): Promise<memory | null>`\n\nretrieve a memory by id.\n\n### `async wipe(): Promise<void>`\n\n**⚠️ danger**: delete all memories, vectors, and waypoints. useful for testing.\n\n---\n\n## license\n\napache 2.0\n\n---\n\n## links\n\n- [main repository](https://github.com/CaviraOSS/LongMemory)\n- [python sdk](https://pypi.org/project/longmemory-py/)\n- [vs code extension](https://marketplace.visualstudio.com/items?itemName=Nullure.longmemory-vscode)\n- [documentation](https://longmemory.cavira.app/docs/sdks/javascript)\n- [discord](https://discord.gg/P7HaRayqTh)\n","readmeFilename":"README.md","_rev":"1-28f8b2076d9c064eb02cc8a496c52734"}