{"_id":"@agentxin-ai/plugin-long-term-memory","name":"@agentxin-ai/plugin-long-term-memory","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.2":{"name":"@agentxin-ai/plugin-long-term-memory","version":"0.0.2","license":"AGPL-3.0","repository":{"type":"git","url":"git+https://github.com/agentxin-ai/agentxin-plugins.git"},"bugs":{"url":"https://github.com/agentxin-ai/agentxin-plugins/issues"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{"./package.json":"./package.json",".":{"@agentxin-plugins-starter/source":"./src/index.ts","types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"dependencies":{"tslib":"^2.3.0"},"peerDependencies":{"zod":"3.25.67","@agentxin-ai/plugin-sdk":"^3.7.0","chalk":"4.1.2","@nestjs/common":"^11.1.6","@nestjs/cqrs":"^11.0.3","@metad/contracts":"^3.7.0","@langchain/core":"0.3.72","@langchain/langgraph":"^0.4.7"},"_id":"@agentxin-ai/plugin-long-term-memory@0.0.2","description":"`@agentxin-ai/plugin-long-term-memory` retrieves relevant long-term memories from a vector store and injects them into the system prompt for [AgentXin AI](https://github.com/agentxin-ai/agentxin) agents. The middleware searches for both profile memories (","homepage":"https://github.com/agentxin-ai/agentxin-plugins#readme","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-WZ51s1bCvE08qXNPC7dBDEwAZTrgi3e2AeLXnz5/IZMsy2JnTkRtZqE/9PDhSiMEyLTgfNKN6l3R/RxeRvq1YA==","shasum":"47a767f48fde79bd37388235f7061de517fb9cd9","tarball":"https://registry.npmjs.org/@agentxin-ai/plugin-long-term-memory/-/plugin-long-term-memory-0.0.2.tgz","fileCount":2,"unpackedSize":7854,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICFP/C0pclsfjdVwN3ru2vHnmn5GYEsvBqFEn7u20WrWAiBVHBOe1lDS5gHtSrUbMuOSZrfezyYFnF32rimLA/iAsw=="}]},"_npmUser":{"name":"agentxin-ai","email":"1304040880@qq.com"},"directories":{},"maintainers":[{"name":"agentxin-ai","email":"1304040880@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plugin-long-term-memory_0.0.2_1773917366010_0.8333712666547015"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-19T10:49:25.925Z","0.0.2":"2026-03-19T10:49:26.170Z","modified":"2026-03-19T10:49:26.372Z"},"maintainers":[{"name":"agentxin-ai","email":"1304040880@qq.com"}],"description":"`@agentxin-ai/plugin-long-term-memory` retrieves relevant long-term memories from a vector store and injects them into the system prompt for [AgentXin AI](https://github.com/agentxin-ai/agentxin) agents. The middleware searches for both profile memories (","homepage":"https://github.com/agentxin-ai/agentxin-plugins#readme","repository":{"type":"git","url":"git+https://github.com/agentxin-ai/agentxin-plugins.git"},"bugs":{"url":"https://github.com/agentxin-ai/agentxin-plugins/issues"},"license":"AGPL-3.0","readme":"# AgentXin Plugin: Long-term Memory Middleware\n\n`@agentxin-ai/plugin-long-term-memory` retrieves relevant long-term memories from a vector store and injects them into the system prompt for [AgentXin AI](https://github.com/agentxin-ai/agentxin) agents. The middleware searches for both profile memories (user preferences, facts) and Q&A memories (historical questions and answers) to provide context-aware responses.\n\n## Key Features\n\n- Retrieves relevant long-term memories using semantic search from LangGraph's BaseStore.\n- Supports two memory types: **Profile** (user attributes, preferences) and **Q&A** (question-answer pairs).\n- Configurable relevance thresholds and result limits per memory type.\n- Optional score display for debugging and transparency.\n- Built-in security: adds instruction hints to prevent prompt injection via stored memories.\n- Character truncation to control prompt size.\n- XML-style formatting for clean memory injection.\n- Deduplication and score-based sorting of search results.\n- Optional debug logging for monitoring memory retrieval statistics.\n\n## Installation\n\n```bash\npnpm add @agentxin-ai/plugin-long-term-memory\n# or\nnpm install @agentxin-ai/plugin-long-term-memory\n```\n\n> **Note**: Ensure the host service already provides `@agentxin-ai/plugin-sdk`, `@nestjs/common@^11`, `@nestjs/cqrs@^11`, `@langchain/core@^0.3`, `@langchain/langgraph@^0.4`, `@metad/contracts`, `zod`, and `chalk`. These are treated as peer/runtime dependencies.\n\n## Quick Start\n\n1. **Register the Plugin**  \n   Start AgentXin with the package in your plugin list:\n   ```sh\n   PLUGINS=@agentxin-ai/plugin-long-term-memory\n   ```\n   The plugin registers the `LongTermMemoryPlugin` module (non-global).\n2. **Enable the Middleware on an Agent**  \n   In the AgentXin console (or agent definition), add a middleware entry with strategy `LongTermMemoryMiddleware` and provide options as needed.\n3. **Configure Memory Types**  \n   Example middleware block:\n   ```json\n   {\n     \"type\": \"LongTermMemoryMiddleware\",\n     \"options\": {\n       \"profile\": {\n         \"enabled\": true,\n         \"limit\": 5,\n         \"scoreThreshold\": 0.7\n       },\n       \"qa\": {\n         \"enabled\": true,\n         \"limit\": 3,\n         \"scoreThreshold\": 0.6\n       },\n       \"wrapperTag\": \"long_term_memories\",\n       \"includeScore\": false,\n       \"maxChars\": 5000,\n       \"instructionHint\": true,\n       \"enableLogging\": false\n     }\n   }\n   ```\n\n## Configuration\n\n| Field | Type | Description | Default |\n| ----- | ---- | ----------- | ------- |\n| `profile` | object | Configuration for profile memory retrieval. | `{ \"enabled\": true, \"limit\": 5, \"scoreThreshold\": 0 }` |\n| `profile.enabled` | boolean | Whether to retrieve profile memories. | `true` |\n| `profile.limit` | number | Maximum number of profile memories to retrieve (1-50). | `5` |\n| `profile.scoreThreshold` | number | Minimum similarity score (0-1) for profile memories. | `0` |\n| `qa` | object | Configuration for Q&A memory retrieval. | `{ \"enabled\": false, \"limit\": 3, \"scoreThreshold\": 0 }` |\n| `qa.enabled` | boolean | Whether to retrieve Q&A memories. | `false` |\n| `qa.limit` | number | Maximum number of Q&A memories to retrieve (1-50). | `3` |\n| `qa.scoreThreshold` | number | Minimum similarity score (0-1) for Q&A memories. | `0` |\n| `wrapperTag` | string | XML-like tag name used to wrap injected memories (1-64 chars). | `\"long_term_memories\"` |\n| `includeScore` | boolean | Include similarity scores in the injected memory block. | `false` |\n| `maxChars` | number | Truncate the total injected memory text to this many characters. 0 means no truncation. | `0` |\n| `instructionHint` | boolean | Add a hint clarifying that memories are data, not instructions. Helps prevent prompt injection. | `true` |\n| `customHint` | string | Custom hint text to use instead of the default (max 500 chars). Leave empty to use default. | `\"\"` |\n| `enableLogging` | boolean | Log memory retrieval statistics for debugging and monitoring. | `false` |\n\n> Tips  \n> - Use `scoreThreshold` to filter out low-relevance memories and reduce noise.  \n> - Enable `includeScore` during development to understand retrieval quality.  \n> - Set `maxChars` to control prompt size when dealing with large memory collections.  \n> - Keep `instructionHint` enabled in production to mitigate prompt injection risks.\n\n## Memory Format\n\n### Profile Memory\nProfile memories represent user attributes, preferences, and facts:\n```xml\n<memory>\n  <memoryId>user-123-pref-1</memoryId>\n  <profile>User prefers dark mode and technical language.</profile>\n</memory>\n```\n\n### Q&A Memory\nQ&A memories capture historical question-answer pairs:\n```xml\n<memory>\n  <memoryId>qa-456</memoryId>\n  <question>What is the company's return policy?</question>\n  <answer>Items can be returned within 30 days with receipt.</answer>\n</memory>\n```\n\n## Middleware Behavior\n\n- **Memory Retrieval**: The middleware searches the LangGraph store using the user's input query. Memories are retrieved from namespaces based on `agentxinId` (or `projectId` as fallback).\n- **Deduplication**: Results are deduplicated by memory key to avoid redundant information.\n- **Sorting**: Memories are sorted by similarity score (highest first) after deduplication.\n- **Injection**: Retrieved memories are formatted and injected into the system prompt before model invocation.\n- **Security**: An instruction hint is added by default to clarify that memories are read-only data, not executable instructions.\n\n## Store Requirements\n\nThis middleware requires a LangGraph `BaseStore` to be available in the runtime. The store can be accessed via:\n- `runtime.store` (direct property)\n- `runtime.configurable.store` (via configurable)\n\nMemory namespaces follow this structure:\n- Profile memories: `[agentxinId, \"profile\"]`\n- Q&A memories: `[agentxinId, \"qa\"]`\n\n## Example Usage\n\n### Basic Configuration\nEnable profile memories only:\n```json\n{\n  \"type\": \"LongTermMemoryMiddleware\",\n  \"options\": {\n    \"profile\": { \"enabled\": true, \"limit\": 5 }\n  }\n}\n```\n\n### Advanced Configuration\nUse both memory types with quality filtering:\n```json\n{\n  \"type\": \"LongTermMemoryMiddleware\",\n  \"options\": {\n    \"profile\": {\n      \"enabled\": true,\n      \"limit\": 10,\n      \"scoreThreshold\": 0.75\n    },\n    \"qa\": {\n      \"enabled\": true,\n      \"limit\": 5,\n      \"scoreThreshold\": 0.7\n    },\n    \"includeScore\": true,\n    \"maxChars\": 8000,\n    \"enableLogging\": true\n  }\n}\n```\n\n## Development & Testing\n\n```bash\nnpm install\nnpx nx build @agentxin-ai/plugin-long-term-memory\nnpx nx test @agentxin-ai/plugin-long-term-memory\n```\n\nTypeScript artifacts emit to `middlewares/long-term-memory/dist`. Validate middleware behavior against a staging agent run before publishing.\n\n## License\n\nThis project follows the [AGPL-3.0 License](../../../LICENSE) located at the repository root.\n","readmeFilename":"README.md","_rev":"1-0371d3690ade7d0141aceb2e06da3b8b"}