@mnemoai/core 1.1.2 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/LICENSE +26 -0
  2. package/README.md +321 -0
  3. package/dist/cli.d.ts +0 -1
  4. package/dist/cli.js +0 -1
  5. package/dist/index.d.ts +0 -115
  6. package/dist/index.js +1 -6
  7. package/dist/src/access-tracker.d.ts +0 -1
  8. package/dist/src/access-tracker.js +0 -1
  9. package/dist/src/adapters/chroma.d.ts +0 -1
  10. package/dist/src/adapters/chroma.js +0 -1
  11. package/dist/src/adapters/lancedb.d.ts +0 -1
  12. package/dist/src/adapters/lancedb.js +0 -1
  13. package/dist/src/adapters/pgvector.d.ts +0 -1
  14. package/dist/src/adapters/pgvector.js +0 -1
  15. package/dist/src/adapters/qdrant.d.ts +0 -1
  16. package/dist/src/adapters/qdrant.js +0 -1
  17. package/dist/src/adaptive-retrieval.d.ts +0 -1
  18. package/dist/src/adaptive-retrieval.js +0 -1
  19. package/dist/src/audit-log.d.ts +0 -1
  20. package/dist/src/audit-log.js +0 -1
  21. package/dist/src/chunker.d.ts +0 -1
  22. package/dist/src/chunker.js +0 -1
  23. package/dist/src/config.d.ts +0 -1
  24. package/dist/src/config.js +0 -1
  25. package/dist/src/decay-engine.d.ts +0 -1
  26. package/dist/src/decay-engine.js +0 -1
  27. package/dist/src/embedder.d.ts +0 -1
  28. package/dist/src/embedder.js +0 -1
  29. package/dist/src/extraction-prompts.d.ts +0 -1
  30. package/dist/src/extraction-prompts.js +0 -1
  31. package/dist/src/license.d.ts +0 -1
  32. package/dist/src/license.js +2 -6
  33. package/dist/src/llm-client.d.ts +0 -1
  34. package/dist/src/llm-client.js +0 -1
  35. package/dist/src/logger.d.ts +0 -1
  36. package/dist/src/logger.js +0 -1
  37. package/dist/src/mcp-server.d.ts +0 -1
  38. package/dist/src/mcp-server.js +0 -1
  39. package/dist/src/memory-categories.d.ts +0 -1
  40. package/dist/src/memory-categories.js +0 -1
  41. package/dist/src/memory-upgrader.d.ts +0 -1
  42. package/dist/src/memory-upgrader.js +0 -1
  43. package/dist/src/migrate.d.ts +0 -1
  44. package/dist/src/migrate.js +0 -1
  45. package/dist/src/mnemo.d.ts +7 -1
  46. package/dist/src/mnemo.js +19 -7
  47. package/dist/src/noise-filter.d.ts +0 -1
  48. package/dist/src/noise-filter.js +0 -1
  49. package/dist/src/noise-prototypes.d.ts +0 -1
  50. package/dist/src/noise-prototypes.js +0 -1
  51. package/dist/src/observability.d.ts +0 -1
  52. package/dist/src/observability.js +0 -1
  53. package/dist/src/query-tracker.d.ts +0 -1
  54. package/dist/src/query-tracker.js +0 -1
  55. package/dist/src/reflection-event-store.d.ts +0 -1
  56. package/dist/src/reflection-event-store.js +0 -1
  57. package/dist/src/reflection-item-store.d.ts +0 -1
  58. package/dist/src/reflection-item-store.js +0 -1
  59. package/dist/src/reflection-mapped-metadata.d.ts +0 -1
  60. package/dist/src/reflection-mapped-metadata.js +0 -1
  61. package/dist/src/reflection-metadata.d.ts +0 -1
  62. package/dist/src/reflection-metadata.js +0 -1
  63. package/dist/src/reflection-ranking.d.ts +0 -1
  64. package/dist/src/reflection-ranking.js +0 -1
  65. package/dist/src/reflection-retry.d.ts +0 -1
  66. package/dist/src/reflection-retry.js +0 -1
  67. package/dist/src/reflection-slices.d.ts +0 -1
  68. package/dist/src/reflection-slices.js +0 -1
  69. package/dist/src/reflection-store.d.ts +0 -1
  70. package/dist/src/reflection-store.js +0 -1
  71. package/dist/src/resonance-state.d.ts +0 -1
  72. package/dist/src/resonance-state.js +0 -1
  73. package/dist/src/retriever.d.ts +0 -1
  74. package/dist/src/retriever.js +0 -1
  75. package/dist/src/scopes.d.ts +0 -1
  76. package/dist/src/scopes.js +0 -1
  77. package/dist/src/self-improvement-files.d.ts +0 -1
  78. package/dist/src/self-improvement-files.js +0 -1
  79. package/dist/src/semantic-gate.d.ts +0 -1
  80. package/dist/src/semantic-gate.js +0 -1
  81. package/dist/src/session-recovery.d.ts +0 -1
  82. package/dist/src/session-recovery.js +0 -1
  83. package/dist/src/smart-extractor.d.ts +0 -1
  84. package/dist/src/smart-extractor.js +0 -1
  85. package/dist/src/smart-metadata.d.ts +0 -1
  86. package/dist/src/smart-metadata.js +0 -1
  87. package/dist/src/storage-adapter.d.ts +0 -1
  88. package/dist/src/storage-adapter.js +0 -1
  89. package/dist/src/store.d.ts +0 -1
  90. package/dist/src/store.js +0 -1
  91. package/dist/src/tier-manager.d.ts +0 -1
  92. package/dist/src/tier-manager.js +0 -1
  93. package/dist/src/tools.d.ts +0 -1
  94. package/dist/src/tools.js +0 -1
  95. package/dist/src/wal-recovery.d.ts +0 -1
  96. package/dist/src/wal-recovery.js +0 -1
  97. package/package.json +1 -1
  98. package/dist/cli.d.ts.map +0 -1
  99. package/dist/cli.js.map +0 -7
  100. package/dist/index.d.ts.map +0 -1
  101. package/dist/index.js.map +0 -7
  102. package/dist/src/access-tracker.d.ts.map +0 -1
  103. package/dist/src/access-tracker.js.map +0 -7
  104. package/dist/src/adapters/chroma.d.ts.map +0 -1
  105. package/dist/src/adapters/chroma.js.map +0 -7
  106. package/dist/src/adapters/lancedb.d.ts.map +0 -1
  107. package/dist/src/adapters/lancedb.js.map +0 -7
  108. package/dist/src/adapters/pgvector.d.ts.map +0 -1
  109. package/dist/src/adapters/pgvector.js.map +0 -7
  110. package/dist/src/adapters/qdrant.d.ts.map +0 -1
  111. package/dist/src/adapters/qdrant.js.map +0 -7
  112. package/dist/src/adaptive-retrieval.d.ts.map +0 -1
  113. package/dist/src/adaptive-retrieval.js.map +0 -7
  114. package/dist/src/audit-log.d.ts.map +0 -1
  115. package/dist/src/audit-log.js.map +0 -7
  116. package/dist/src/chunker.d.ts.map +0 -1
  117. package/dist/src/chunker.js.map +0 -7
  118. package/dist/src/config.d.ts.map +0 -1
  119. package/dist/src/config.js.map +0 -7
  120. package/dist/src/decay-engine.d.ts.map +0 -1
  121. package/dist/src/decay-engine.js.map +0 -7
  122. package/dist/src/embedder.d.ts.map +0 -1
  123. package/dist/src/embedder.js.map +0 -7
  124. package/dist/src/extraction-prompts.d.ts.map +0 -1
  125. package/dist/src/extraction-prompts.js.map +0 -7
  126. package/dist/src/license.d.ts.map +0 -1
  127. package/dist/src/license.js.map +0 -7
  128. package/dist/src/llm-client.d.ts.map +0 -1
  129. package/dist/src/llm-client.js.map +0 -7
  130. package/dist/src/logger.d.ts.map +0 -1
  131. package/dist/src/logger.js.map +0 -7
  132. package/dist/src/mcp-server.d.ts.map +0 -1
  133. package/dist/src/mcp-server.js.map +0 -7
  134. package/dist/src/memory-categories.d.ts.map +0 -1
  135. package/dist/src/memory-categories.js.map +0 -7
  136. package/dist/src/memory-upgrader.d.ts.map +0 -1
  137. package/dist/src/memory-upgrader.js.map +0 -7
  138. package/dist/src/migrate.d.ts.map +0 -1
  139. package/dist/src/migrate.js.map +0 -7
  140. package/dist/src/mnemo.d.ts.map +0 -1
  141. package/dist/src/mnemo.js.map +0 -7
  142. package/dist/src/noise-filter.d.ts.map +0 -1
  143. package/dist/src/noise-filter.js.map +0 -7
  144. package/dist/src/noise-prototypes.d.ts.map +0 -1
  145. package/dist/src/noise-prototypes.js.map +0 -7
  146. package/dist/src/observability.d.ts.map +0 -1
  147. package/dist/src/observability.js.map +0 -7
  148. package/dist/src/query-tracker.d.ts.map +0 -1
  149. package/dist/src/query-tracker.js.map +0 -7
  150. package/dist/src/reflection-event-store.d.ts.map +0 -1
  151. package/dist/src/reflection-event-store.js.map +0 -7
  152. package/dist/src/reflection-item-store.d.ts.map +0 -1
  153. package/dist/src/reflection-item-store.js.map +0 -7
  154. package/dist/src/reflection-mapped-metadata.d.ts.map +0 -1
  155. package/dist/src/reflection-mapped-metadata.js.map +0 -7
  156. package/dist/src/reflection-metadata.d.ts.map +0 -1
  157. package/dist/src/reflection-metadata.js.map +0 -7
  158. package/dist/src/reflection-ranking.d.ts.map +0 -1
  159. package/dist/src/reflection-ranking.js.map +0 -7
  160. package/dist/src/reflection-retry.d.ts.map +0 -1
  161. package/dist/src/reflection-retry.js.map +0 -7
  162. package/dist/src/reflection-slices.d.ts.map +0 -1
  163. package/dist/src/reflection-slices.js.map +0 -7
  164. package/dist/src/reflection-store.d.ts.map +0 -1
  165. package/dist/src/reflection-store.js.map +0 -7
  166. package/dist/src/resonance-state.d.ts.map +0 -1
  167. package/dist/src/resonance-state.js.map +0 -7
  168. package/dist/src/retriever.d.ts.map +0 -1
  169. package/dist/src/retriever.js.map +0 -7
  170. package/dist/src/scopes.d.ts.map +0 -1
  171. package/dist/src/scopes.js.map +0 -7
  172. package/dist/src/self-improvement-files.d.ts.map +0 -1
  173. package/dist/src/self-improvement-files.js.map +0 -7
  174. package/dist/src/semantic-gate.d.ts.map +0 -1
  175. package/dist/src/semantic-gate.js.map +0 -7
  176. package/dist/src/session-recovery.d.ts.map +0 -1
  177. package/dist/src/session-recovery.js.map +0 -7
  178. package/dist/src/smart-extractor.d.ts.map +0 -1
  179. package/dist/src/smart-extractor.js.map +0 -7
  180. package/dist/src/smart-metadata.d.ts.map +0 -1
  181. package/dist/src/smart-metadata.js.map +0 -7
  182. package/dist/src/storage-adapter.d.ts.map +0 -1
  183. package/dist/src/storage-adapter.js.map +0 -7
  184. package/dist/src/store.d.ts.map +0 -1
  185. package/dist/src/store.js.map +0 -7
  186. package/dist/src/tier-manager.d.ts.map +0 -1
  187. package/dist/src/tier-manager.js.map +0 -7
  188. package/dist/src/tools.d.ts.map +0 -1
  189. package/dist/src/tools.js.map +0 -7
  190. package/dist/src/wal-recovery.d.ts.map +0 -1
  191. package/dist/src/wal-recovery.js.map +0 -7
package/LICENSE ADDED
@@ -0,0 +1,26 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mnemo Contributors
4
+
5
+ NOTE: This MIT license applies to files marked with
6
+ `SPDX-License-Identifier: MIT`. Files marked with
7
+ `SPDX-License-Identifier: LicenseRef-Mnemo-Pro` are under
8
+ a separate commercial license — see packages/pro/LICENSE.
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,321 @@
1
+ <p align="center">
2
+ <img src="docs/logo.svg" width="80" alt="Mnemo" />
3
+ </p>
4
+
5
+ <h1 align="center">Mnemo</h1>
6
+
7
+ <p align="center">
8
+ <a href="https://www.npmjs.com/package/@mnemoai/core"><img src="https://img.shields.io/npm/v/@mnemoai/core?color=4ecdc4&label=npm" alt="npm"></a>
9
+ <a href="https://github.com/Methux/mnemo/actions"><img src="https://github.com/Methux/mnemo/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
10
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
11
+ <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
12
+ </p>
13
+
14
+ <p align="center">
15
+ <strong>AI memory that forgets intelligently.</strong><br>
16
+ The first memory framework built on cognitive science.
17
+ </p>
18
+
19
+ <p align="center">
20
+ <a href="#quick-start">Quick Start</a> ·
21
+ <a href="#architecture">Architecture</a> ·
22
+ <a href="#core-vs-pro">Core vs Pro</a> ·
23
+ <a href="https://m-nemo.ai">Website</a> ·
24
+ <a href="docs/api-reference.md">API</a>
25
+ </p>
26
+
27
+ ---
28
+
29
+ ## Why Mnemo?
30
+
31
+ Every AI memory solution stores memories. **Mnemo is the first to forget intelligently.**
32
+
33
+ Humans don't remember everything equally — important memories consolidate, trivial ones fade, frequently recalled knowledge strengthens. Mnemo models this with:
34
+
35
+ - **Weibull decay** — stretched-exponential forgetting: `exp(-(t/λ)^β)` with tier-specific β
36
+ - **Triple-path retrieval** — Vector + BM25 + Knowledge Graph fused with RRF
37
+ - **Three-layer contradiction detection** — regex signal → LLM 5-class → dedup pipeline
38
+ - **10-stage retrieval pipeline** — from preprocessing to context injection
39
+
40
+ The result: your AI agent's memory stays relevant instead of drowning in noise.
41
+
42
+ ## Mnemo vs Paid Competitors
43
+
44
+ | Capability | Mem0 $249 | Zep $199 | Letta $49 | Cognee $149 | **Mnemo Core** FREE | **Mnemo Pro** $69 |
45
+ |:---|:---:|:---:|:---:|:---:|:---:|:---:|
46
+ | Vector search | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
47
+ | BM25 keyword search | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
48
+ | Knowledge graph | Pro | ✅ | ❌ | ✅ | ✅ | ✅ |
49
+ | Forgetting model | ❌ | Basic | Basic | ❌ | **Weibull** | **Weibull** |
50
+ | Memory tiers | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
51
+ | Cross-encoder rerank | ❌ | Basic | ❌ | ❌ | ✅ | ✅ |
52
+ | Contradiction detection | ❌ | ✅ | ❌ | Partial | ✅ | ✅ |
53
+ | Triple-path fusion | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
54
+ | Scope isolation | Basic | ❌ | ❌ | ❌ | ✅ | ✅ |
55
+ | Emotional salience | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
56
+ | WAL crash recovery | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
57
+ | Session reflection | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ |
58
+ | Self-improvement | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
59
+ | Observability | Partial | ✅ | ❌ | ❌ | ❌ | ✅ |
60
+ | Self-hosted | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
61
+
62
+ > Mnemo Core (free) already outperforms most $99+/mo paid solutions on retrieval quality.
63
+
64
+ ---
65
+
66
+ ## Architecture
67
+
68
+ ```
69
+ ┌─────────────── Write Layer (6 channels) ───────────────┐
70
+ │ ① Hook realtime ④ Daily archive extractor │
71
+ │ ② Plugin SmartExtract ⑤ File watcher (fs.watch) │
72
+ │ ③ L1 Distiller (cron) ⑥ Manual memory_store │
73
+ └────────────────────────┬───────────────────────────────┘
74
+
75
+ store.ts (dedup + contradiction L1)
76
+ ┌────┴────┐
77
+ ▼ ▼
78
+ LanceDB Graphiti/Neo4j
79
+ (Vec + BM25) (Knowledge Graph + WAL)
80
+
81
+ ┌─────────────── Retrieval Layer (10 stages) ─────────────┐
82
+ │ S0 Preprocessing S5 Min-score filter │
83
+ │ S1 Resonance gate S6 Cross-encoder rerank │
84
+ │ S2 Multi-hop detection S7 Weibull decay │
85
+ │ S3 Triple-path parallel S8 Hard cutoff + normalize │
86
+ │ (Vector‖BM25‖Graph) S9 MMR deduplication │
87
+ │ S4 RRF fusion S10 Session dedup + inject │
88
+ └────────────────────────┬────────────────────────────────┘
89
+
90
+ Top-K → Agent Context
91
+
92
+ ┌─────────────── Lifecycle Layer ─────────────────────────┐
93
+ │ Tier classification: Core (β=0.8) → Working (β=1.0) │
94
+ │ → Peripheral (β=1.3) │
95
+ │ Weibull decay: exp(-(t/λ)^β) │
96
+ │ Access reinforcement (spaced repetition) │
97
+ │ Emotional salience modulation (up to 1.5×) │
98
+ │ Session reflection + overnight consolidation │
99
+ └─────────────────────────────────────────────────────────┘
100
+ ```
101
+
102
+ ---
103
+
104
+ ## Quick Start
105
+
106
+ ### Option 1: Docker (recommended)
107
+
108
+ ```bash
109
+ git clone https://github.com/Methux/mnemo.git
110
+ cd mnemo
111
+ cp .env.example .env # add your API keys
112
+ docker compose up -d # starts Neo4j + Graphiti + Dashboard
113
+ ```
114
+
115
+ Dashboard at `http://localhost:18800`
116
+
117
+ ### Option 2: 100% Local ($0, no external API)
118
+
119
+ ```bash
120
+ # Install Ollama models
121
+ ollama pull nomic-embed-text # embedding
122
+ ollama pull qwen3:8b # smart extraction LLM
123
+ ollama pull bge-reranker-v2-m3 # cross-encoder rerank
124
+
125
+ # Use local config
126
+ cp config/mnemo.local.example.json ~/.mnemo/mnemo.json
127
+ docker compose up -d # Neo4j + Graphiti
128
+ ```
129
+
130
+ Full Core functionality — embedding, extraction, rerank, graph — all running locally. Zero API cost.
131
+
132
+ ### Option 3: npm
133
+
134
+ ```bash
135
+ npm install @mnemoai/core
136
+ ```
137
+
138
+ ```typescript
139
+ import { createMnemo } from '@mnemoai/core';
140
+
141
+ const mnemo = await createMnemo({
142
+ embedding: {
143
+ provider: 'openai-compatible',
144
+ apiKey: process.env.VOYAGE_API_KEY,
145
+ baseURL: 'https://api.voyageai.com/v1',
146
+ model: 'voyage-3-large',
147
+ dimensions: 1024,
148
+ },
149
+ dbPath: './memory-db',
150
+ });
151
+
152
+ // Store a memory
153
+ await mnemo.store({
154
+ text: 'User prefers dark mode and minimal UI',
155
+ category: 'preference',
156
+ importance: 0.8,
157
+ });
158
+
159
+ // Recall — automatically applies decay, rerank, MMR
160
+ const results = await mnemo.recall('UI preferences', { limit: 5 });
161
+ ```
162
+
163
+ ### Option 4: Interactive Setup
164
+
165
+ ```bash
166
+ npm run init # guided wizard — generates config + .env
167
+ ```
168
+
169
+ ### Option 5: OpenClaw Plugin
170
+
171
+ ```bash
172
+ openclaw plugins install mnemo
173
+ ```
174
+
175
+ ---
176
+
177
+ ## Core vs Pro
178
+
179
+ ### Mnemo Core — Free, MIT License
180
+
181
+ The open-source foundation. Full retrieval engine, no restrictions.
182
+
183
+ | Feature | Details |
184
+ |:---|:---|
185
+ | Storage | Pluggable backend — LanceDB (default), Qdrant, Chroma, PGVector |
186
+ | Retrieval | Triple-path (Vector + BM25 + Graphiti) with RRF fusion |
187
+ | Rerank | Cross-encoder (Voyage rerank-2) |
188
+ | Decay | Weibull stretched-exponential, tier-specific β |
189
+ | Tiers | Core (β=0.8) / Working (β=1.0) / Peripheral (β=1.3) |
190
+ | Contradiction | Three-layer detection (regex + LLM + dedup) |
191
+ | Extraction | Smart extraction with GPT-4.1 |
192
+ | Graph | Graphiti/Neo4j knowledge graph |
193
+ | Scopes | Multi-agent isolation |
194
+ | Emotional salience | Amygdala-modeled half-life adjustment |
195
+ | Noise filtering | Embedding-based noise bank + regex |
196
+ | Temporal queries | Date format expansion (中/EN) |
197
+
198
+ ### Mnemo Pro — From $69/mo
199
+
200
+ Everything in Core, plus enterprise features:
201
+
202
+ | Feature | Details |
203
+ |:---|:---|
204
+ | WAL | Write-ahead log for crash recovery |
205
+ | Session reflection | Deep summary at session boundaries |
206
+ | Self-improvement | Learning from interaction patterns |
207
+ | Memory tools | memory_store / search / delete for agents |
208
+ | MCP Server | Model Context Protocol integration |
209
+ | Observability | Query tracking, latency monitoring, health checks |
210
+ | Access tracking | Spaced repetition with reinforcement |
211
+
212
+ ```bash
213
+ # Activate Pro
214
+ export MNEMO_LICENSE_TOKEN="mnemo_your_token"
215
+ # Auto-activates on first run, binds to this machine
216
+ ```
217
+
218
+ ### Pricing
219
+
220
+ | Plan | Price | Devices | Support |
221
+ |:---|:---|:---:|:---|
222
+ | **Core** | Free forever | Unlimited | GitHub Issues |
223
+ | **Indie** | $69/mo · $690/yr | 1 | Email |
224
+ | **Team** | $199/mo · $1,990/yr | 5 | Priority + Slack |
225
+ | **Enterprise** | Custom | Unlimited | Dedicated + SLA |
226
+
227
+ [Get Mnemo Pro →](https://m-nemo.ai/pro)
228
+
229
+ ### API Configuration Guide
230
+
231
+ Mnemo requires external models for embedding, extraction, and reranking. **You bring your own API keys** — Mnemo does not proxy or bundle API costs. Choose a setup that fits your budget:
232
+
233
+ | Setup | Embedding | LLM Extraction | Rerank | Est. API Cost |
234
+ |:---|:---|:---|:---|:---:|
235
+ | **Local** | Ollama nomic-embed-text | Ollama qwen3:8b | Ollama bge-reranker | **$0/mo** |
236
+ | **Hybrid** | Voyage voyage-3-large | GPT-4.1-mini | Voyage rerank-2 | ~$20/mo |
237
+ | **Cloud** | Voyage voyage-3-large | GPT-4.1 | Voyage rerank-2 | ~$45/mo |
238
+
239
+ > These are **your own API costs**, not Mnemo subscription fees. All setups use the same Core/Pro features — the difference is model quality.
240
+ >
241
+ > - **Local**: Runs entirely offline via [Ollama](https://ollama.com). Good enough to beat most paid competitors.
242
+ > - **Hybrid**: Best quality-to-cost ratio. Recommended for most users.
243
+ > - **Cloud**: Maximum extraction quality for high-volume production.
244
+ >
245
+ > See `config/mnemo.local.example.json` for the $0 local setup, or `config/mnemo.example.json` for the cloud setup.
246
+
247
+ ---
248
+
249
+ ## Cognitive Science
250
+
251
+ Mnemo's design maps directly to established memory research:
252
+
253
+ | Human Memory | Mnemo Implementation |
254
+ |:---|:---|
255
+ | Ebbinghaus forgetting curve | Weibull decay: `exp(-(t/λ)^β)` |
256
+ | Spaced repetition effect | Access reinforcement extends half-life |
257
+ | Memory consolidation (sleep) | Session reflection + overnight cron |
258
+ | Core vs peripheral memory | Tier system with differential β |
259
+ | Spreading activation | Graphiti 1-hop neighborhood traversal |
260
+ | Amygdala emotional tagging | emotionalSalience modulates half-life (up to 1.5×) |
261
+ | Interference / false memories | MMR deduplication + noise bank |
262
+ | Selective attention | Resonance gating (adaptive threshold) |
263
+ | Metamemory | mnemo-doctor + Web Dashboard |
264
+
265
+ ---
266
+
267
+ ## Tools
268
+
269
+ | Tool | Description | Run |
270
+ |:---|:---|:---|
271
+ | `mnemo init` | Interactive config wizard | `npm run init` |
272
+ | `mnemo-doctor` | One-command health check | `npm run doctor` |
273
+ | `validate-config` | Config validation gate | `npm run validate` |
274
+ | Dashboard | Web UI for browsing, debugging, monitoring | `http://localhost:18800` |
275
+
276
+ ---
277
+
278
+ ## Documentation
279
+
280
+ - [Architecture Deep Dive](docs/architecture.md)
281
+ - [Configuration Reference](docs/configuration.md)
282
+ - [Retrieval Pipeline](docs/retrieval-pipeline.md)
283
+ - [Cognitive Science Model](docs/cognitive-science.md)
284
+ - [API Reference](docs/api-reference.md)
285
+ - [OpenClaw Integration](docs/openclaw-integration.md)
286
+
287
+ ---
288
+
289
+ ## License
290
+
291
+ This project uses a dual-license model:
292
+
293
+ - **MIT** — Files marked `SPDX-License-Identifier: MIT` (Core features)
294
+ - **Commercial** — Files marked `SPDX-License-Identifier: LicenseRef-Mnemo-Pro` (Pro features)
295
+
296
+ See [LICENSE](LICENSE) and [packages/pro/LICENSE](packages/pro/LICENSE) for details.
297
+
298
+ ---
299
+
300
+ ## Contributing
301
+
302
+ We welcome contributions to Mnemo Core (MIT-licensed files). See [CONTRIBUTING.md](CONTRIBUTING.md).
303
+
304
+ Areas where we'd love help:
305
+ - Benchmark evaluation (LOCOMO, MemBench)
306
+ - New embedding provider adapters
307
+ - Retrieval pipeline optimizations
308
+ - Language-specific SDKs (Python, Go)
309
+ - Documentation and examples
310
+
311
+ ---
312
+
313
+ <p align="center">
314
+ <sub>Built with cognitive science, not hype.</sub>
315
+ </p>
316
+
317
+ ---
318
+
319
+ <sub>
320
+ **Trademarks:** LanceDB is a trademark of LanceDB, Inc. Neo4j is a trademark of Neo4j, Inc. Qdrant is a trademark of Qdrant Solutions GmbH. Mnemo is not affiliated with, endorsed by, or sponsored by any of these organizations. Storage backends are used under their respective open-source licenses.
321
+ </sub>
package/dist/cli.d.ts CHANGED
@@ -1,2 +1 @@
1
1
  export declare function createMemoryCLI(..._args: any[]): any;
2
- //# sourceMappingURL=cli.d.ts.map
package/dist/cli.js CHANGED
@@ -4,4 +4,3 @@ function createMemoryCLI(..._args) {
4
4
  export {
5
5
  createMemoryCLI
6
6
  };
7
- //# sourceMappingURL=cli.js.map
package/dist/index.d.ts CHANGED
@@ -3,119 +3,6 @@
3
3
  * Cognitive memory framework with hybrid retrieval, multi-scope isolation, and management CLI
4
4
  */
5
5
  import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
6
- interface PluginConfig {
7
- embedding: {
8
- provider: "openai-compatible";
9
- apiKey: string | string[];
10
- model?: string;
11
- baseURL?: string;
12
- dimensions?: number;
13
- taskQuery?: string;
14
- taskPassage?: string;
15
- normalized?: boolean;
16
- chunking?: boolean;
17
- };
18
- dbPath?: string;
19
- autoCapture?: boolean;
20
- autoRecall?: boolean;
21
- autoRecallMinLength?: number;
22
- autoRecallMinRepeated?: number;
23
- captureAssistant?: boolean;
24
- retrieval?: {
25
- mode?: "hybrid" | "vector";
26
- vectorWeight?: number;
27
- bm25Weight?: number;
28
- minScore?: number;
29
- rerank?: "cross-encoder" | "lightweight" | "none";
30
- candidatePoolSize?: number;
31
- rerankApiKey?: string;
32
- rerankModel?: string;
33
- rerankEndpoint?: string;
34
- rerankProvider?: "jina" | "siliconflow" | "voyage" | "pinecone";
35
- recencyHalfLifeDays?: number;
36
- recencyWeight?: number;
37
- filterNoise?: boolean;
38
- lengthNormAnchor?: number;
39
- hardMinScore?: number;
40
- timeDecayHalfLifeDays?: number;
41
- reinforcementFactor?: number;
42
- maxHalfLifeMultiplier?: number;
43
- };
44
- decay?: {
45
- recencyHalfLifeDays?: number;
46
- recencyWeight?: number;
47
- frequencyWeight?: number;
48
- intrinsicWeight?: number;
49
- staleThreshold?: number;
50
- searchBoostMin?: number;
51
- importanceModulation?: number;
52
- betaCore?: number;
53
- betaWorking?: number;
54
- betaPeripheral?: number;
55
- coreDecayFloor?: number;
56
- workingDecayFloor?: number;
57
- peripheralDecayFloor?: number;
58
- };
59
- tier?: {
60
- coreAccessThreshold?: number;
61
- coreCompositeThreshold?: number;
62
- coreImportanceThreshold?: number;
63
- peripheralCompositeThreshold?: number;
64
- peripheralAgeDays?: number;
65
- workingAccessThreshold?: number;
66
- workingCompositeThreshold?: number;
67
- };
68
- smartExtraction?: boolean;
69
- llm?: {
70
- apiKey?: string;
71
- model?: string;
72
- baseURL?: string;
73
- };
74
- extractMinMessages?: number;
75
- extractMaxChars?: number;
76
- scopes?: {
77
- default?: string;
78
- definitions?: Record<string, {
79
- description: string;
80
- }>;
81
- agentAccess?: Record<string, string[]>;
82
- };
83
- enableManagementTools?: boolean;
84
- sessionStrategy?: SessionStrategy;
85
- sessionMemory?: {
86
- enabled?: boolean;
87
- messageCount?: number;
88
- };
89
- selfImprovement?: {
90
- enabled?: boolean;
91
- beforeResetNote?: boolean;
92
- skipSubagentBootstrap?: boolean;
93
- ensureLearningFiles?: boolean;
94
- };
95
- memoryReflection?: {
96
- enabled?: boolean;
97
- storeToLanceDB?: boolean;
98
- writeLegacyCombined?: boolean;
99
- injectMode?: ReflectionInjectMode;
100
- agentId?: string;
101
- messageCount?: number;
102
- maxInputChars?: number;
103
- timeoutMs?: number;
104
- thinkLevel?: ReflectionThinkLevel;
105
- errorReminderMaxEntries?: number;
106
- dedupeErrorSignals?: boolean;
107
- };
108
- mdMirror?: {
109
- enabled?: boolean;
110
- dir?: string;
111
- };
112
- }
113
- type ReflectionThinkLevel = "off" | "minimal" | "low" | "medium" | "high";
114
- type SessionStrategy = "memoryReflection" | "systemSessionMemory" | "none";
115
- type ReflectionInjectMode = "inheritance-only" | "inheritance+derived";
116
- export declare function readSessionConversationWithResetFallback(sessionFilePath: string, messageCount: number): Promise<string | null>;
117
- export declare function shouldCapture(text: string): boolean;
118
- export declare function detectCategory(text: string): "preference" | "fact" | "decision" | "entity" | "other";
119
6
  declare const memoryLanceDBProPlugin: {
120
7
  id: string;
121
8
  name: string;
@@ -123,7 +10,6 @@ declare const memoryLanceDBProPlugin: {
123
10
  kind: "memory";
124
11
  register(api: OpenClawPluginApi): void;
125
12
  };
126
- export declare function parsePluginConfig(value: unknown): PluginConfig;
127
13
  export default memoryLanceDBProPlugin;
128
14
  export { createMnemo } from "./src/mnemo.js";
129
15
  export type { MnemoConfig, MnemoInstance } from "./src/mnemo.js";
@@ -133,4 +19,3 @@ export type { StorageAdapter } from "./src/storage-adapter.js";
133
19
  export { registerAdapter, createAdapter, listAdapters } from "./src/storage-adapter.js";
134
20
  export { log, setLogger } from "./src/logger.js";
135
21
  export type { Logger } from "./src/logger.js";
136
- //# sourceMappingURL=index.d.ts.map
package/dist/index.js CHANGED
@@ -2587,13 +2587,8 @@ export {
2587
2587
  createAdapter,
2588
2588
  createMnemo,
2589
2589
  index_default as default,
2590
- detectCategory,
2591
2590
  listAdapters,
2592
2591
  log,
2593
- parsePluginConfig,
2594
- readSessionConversationWithResetFallback,
2595
2592
  registerAdapter,
2596
- setLogger,
2597
- shouldCapture
2593
+ setLogger
2598
2594
  };
2599
- //# sourceMappingURL=index.js.map
@@ -94,4 +94,3 @@ export declare class AccessTracker {
94
94
  private resetTimer;
95
95
  private clearTimer;
96
96
  }
97
- //# sourceMappingURL=access-tracker.d.ts.map
@@ -181,4 +181,3 @@ export {
181
181
  computeEffectiveHalfLife,
182
182
  parseAccessMetadata
183
183
  };
184
- //# sourceMappingURL=access-tracker.js.map
@@ -28,4 +28,3 @@ export declare class ChromaAdapter implements StorageAdapter {
28
28
  hasFullTextSearch(): boolean;
29
29
  close(): Promise<void>;
30
30
  }
31
- //# sourceMappingURL=chroma.d.ts.map
@@ -141,4 +141,3 @@ registerAdapter("chroma", (config) => new ChromaAdapter(config));
141
141
  export {
142
142
  ChromaAdapter
143
143
  };
144
- //# sourceMappingURL=chroma.js.map
@@ -26,4 +26,3 @@ export declare class LanceDBAdapter implements StorageAdapter {
26
26
  close(): Promise<void>;
27
27
  private toRecord;
28
28
  }
29
- //# sourceMappingURL=lancedb.d.ts.map
@@ -166,4 +166,3 @@ registerAdapter("lancedb", () => new LanceDBAdapter());
166
166
  export {
167
167
  LanceDBAdapter
168
168
  };
169
- //# sourceMappingURL=lancedb.js.map
@@ -30,4 +30,3 @@ export declare class PGVectorAdapter implements StorageAdapter {
30
30
  close(): Promise<void>;
31
31
  private toRecord;
32
32
  }
33
- //# sourceMappingURL=pgvector.d.ts.map
@@ -153,4 +153,3 @@ registerAdapter("pgvector", (config) => new PGVectorAdapter(config));
153
153
  export {
154
154
  PGVectorAdapter
155
155
  };
156
- //# sourceMappingURL=pgvector.js.map
@@ -31,4 +31,3 @@ export declare class QdrantAdapter implements StorageAdapter {
31
31
  private toRecord;
32
32
  private parseFilter;
33
33
  }
34
- //# sourceMappingURL=qdrant.d.ts.map
@@ -129,4 +129,3 @@ registerAdapter("qdrant", (config) => new QdrantAdapter(config));
129
129
  export {
130
130
  QdrantAdapter
131
131
  };
132
- //# sourceMappingURL=qdrant.js.map
@@ -11,4 +11,3 @@
11
11
  * @param minLength Optional minimum length override (if set, overrides built-in thresholds)
12
12
  */
13
13
  export declare function shouldSkipRetrieval(query: string, minLength?: number): boolean;
14
- //# sourceMappingURL=adaptive-retrieval.d.ts.map
@@ -49,4 +49,3 @@ function shouldSkipRetrieval(query, minLength) {
49
49
  export {
50
50
  shouldSkipRetrieval
51
51
  };
52
- //# sourceMappingURL=adaptive-retrieval.js.map
@@ -53,4 +53,3 @@ export declare function readAuditLog(startDate: string, endDate: string): Promis
53
53
  * Enable or disable audit logging.
54
54
  */
55
55
  export declare function setAuditEnabled(enabled: boolean): void;
56
- //# sourceMappingURL=audit-log.d.ts.map
@@ -136,4 +136,3 @@ export {
136
136
  readAuditLog,
137
137
  setAuditEnabled
138
138
  };
139
- //# sourceMappingURL=audit-log.js.map
@@ -42,4 +42,3 @@ export declare function chunkDocument(text: string, config?: ChunkerConfig): Chu
42
42
  */
43
43
  export declare function smartChunk(text: string, embedderModel?: string): ChunkResult;
44
44
  export default chunkDocument;
45
- //# sourceMappingURL=chunker.d.ts.map
@@ -154,4 +154,3 @@ export {
154
154
  chunker_default as default,
155
155
  smartChunk
156
156
  };
157
- //# sourceMappingURL=chunker.js.map
@@ -67,4 +67,3 @@ export declare function resolveEnvVars(value: string): string;
67
67
  export declare function parsePositiveInt(value: unknown): number | undefined;
68
68
  export declare function parsePluginConfig(value: unknown): PluginConfig;
69
69
  export declare function loadConfigFromOpenClaw(): PluginConfig;
70
- //# sourceMappingURL=config.d.ts.map
@@ -139,4 +139,3 @@ export {
139
139
  parsePositiveInt,
140
140
  resolveEnvVars
141
141
  };
142
- //# sourceMappingURL=config.js.map
@@ -70,4 +70,3 @@ export interface DecayEngine {
70
70
  getStaleMemories(memories: DecayableMemory[], now?: number): DecayScore[];
71
71
  }
72
72
  export declare function createDecayEngine(config?: DecayConfig): DecayEngine;
73
- //# sourceMappingURL=decay-engine.d.ts.map
@@ -116,4 +116,3 @@ export {
116
116
  DEFAULT_DECAY_CONFIG,
117
117
  createDecayEngine
118
118
  };
119
- //# sourceMappingURL=decay-engine.js.map
@@ -91,4 +91,3 @@ export declare class Embedder {
91
91
  };
92
92
  }
93
93
  export declare function createEmbedder(config: EmbeddingConfig): Embedder;
94
- //# sourceMappingURL=embedder.d.ts.map
@@ -534,4 +534,3 @@ export {
534
534
  formatEmbeddingProviderError,
535
535
  getVectorDimensions
536
536
  };
537
- //# sourceMappingURL=embedder.js.map
@@ -9,4 +9,3 @@ export declare function buildExtractionPrompt(conversationText: string, user: st
9
9
  export declare function buildChineseExtractionPrompt(conversationText: string, user: string): string;
10
10
  export declare function buildDedupPrompt(candidateAbstract: string, candidateOverview: string, candidateContent: string, existingMemories: string): string;
11
11
  export declare function buildMergePrompt(existingAbstract: string, existingOverview: string, existingContent: string, newAbstract: string, newOverview: string, newContent: string, category: string): string;
12
- //# sourceMappingURL=extraction-prompts.d.ts.map
@@ -308,4 +308,3 @@ export {
308
308
  buildExtractionPrompt,
309
309
  buildMergePrompt
310
310
  };
311
- //# sourceMappingURL=extraction-prompts.js.map
@@ -26,4 +26,3 @@ export declare function ensureProLicense(): Promise<boolean>;
26
26
  export declare function getLicenseInfo(): LicensePayload | null;
27
27
  export declare function requirePro(featureName: string): boolean;
28
28
  export declare function _resetLicenseCache(): void;
29
- //# sourceMappingURL=license.d.ts.map