mnemolite 0.1.0__tar.gz
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.
- mnemolite-0.1.0/CHANGELOG.md +69 -0
- mnemolite-0.1.0/LICENSE +7 -0
- mnemolite-0.1.0/MANIFEST.in +8 -0
- mnemolite-0.1.0/PKG-INFO +162 -0
- mnemolite-0.1.0/README.md +127 -0
- mnemolite-0.1.0/docs/decisions.md +334 -0
- mnemolite-0.1.0/docs/extraction.md +90 -0
- mnemolite-0.1.0/docs/skill.md +104 -0
- mnemolite-0.1.0/docs/status.md +272 -0
- mnemolite-0.1.0/mnemolite/__init__.py +5 -0
- mnemolite-0.1.0/mnemolite/_constants.py +23 -0
- mnemolite-0.1.0/mnemolite/brief.py +72 -0
- mnemolite-0.1.0/mnemolite/consolidator.py +335 -0
- mnemolite-0.1.0/mnemolite/core.py +288 -0
- mnemolite-0.1.0/mnemolite/db.py +656 -0
- mnemolite-0.1.0/mnemolite/embedder.py +176 -0
- mnemolite-0.1.0/mnemolite/server.py +226 -0
- mnemolite-0.1.0/mnemolite.egg-info/PKG-INFO +162 -0
- mnemolite-0.1.0/mnemolite.egg-info/SOURCES.txt +43 -0
- mnemolite-0.1.0/mnemolite.egg-info/dependency_links.txt +1 -0
- mnemolite-0.1.0/mnemolite.egg-info/entry_points.txt +2 -0
- mnemolite-0.1.0/mnemolite.egg-info/requires.txt +13 -0
- mnemolite-0.1.0/mnemolite.egg-info/top_level.txt +1 -0
- mnemolite-0.1.0/pyproject.toml +51 -0
- mnemolite-0.1.0/requirements.txt +5 -0
- mnemolite-0.1.0/setup.cfg +4 -0
- mnemolite-0.1.0/skill/README.md +105 -0
- mnemolite-0.1.0/skill/mnemolite-memory/SKILL.md +242 -0
- mnemolite-0.1.0/skill/mnemolite-memory/examples/forget-and-decay.md +90 -0
- mnemolite-0.1.0/skill/mnemolite-memory/examples/save-and-recall.md +98 -0
- mnemolite-0.1.0/skill/mnemolite-memory/examples/session-start.md +64 -0
- mnemolite-0.1.0/skill/mnemolite-memory/references/memory-policy.md +120 -0
- mnemolite-0.1.0/skill/mnemolite-memory/references/tools.md +165 -0
- mnemolite-0.1.0/skill/mnemolite-memory/references/troubleshooting.md +110 -0
- mnemolite-0.1.0/skill/mnemolite-memory/scripts/mcp_config.json +11 -0
- mnemolite-0.1.0/skill/mnemolite-memory/scripts/verify_tools.py +58 -0
- mnemolite-0.1.0/tests/__init__.py +0 -0
- mnemolite-0.1.0/tests/conftest.py +83 -0
- mnemolite-0.1.0/tests/test_brief.py +67 -0
- mnemolite-0.1.0/tests/test_consolidation.py +196 -0
- mnemolite-0.1.0/tests/test_db.py +390 -0
- mnemolite-0.1.0/tests/test_extraction.py +140 -0
- mnemolite-0.1.0/tests/test_recall.py +394 -0
- mnemolite-0.1.0/tests/test_server.py +32 -0
- mnemolite-0.1.0/tests/test_skill.py +72 -0
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to Mnemolite are documented here.
|
|
4
|
+
|
|
5
|
+
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
|
|
6
|
+
and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [0.1.0] - 2026-11-18
|
|
9
|
+
|
|
10
|
+
First packaged release of Mnemolite.
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Local-first episodic memory in SQLite and ChromaDB with a semantic graph in
|
|
15
|
+
SQLite.
|
|
16
|
+
- Zero-LLM consolidation: spaCy entity and triple extraction, lemmatized
|
|
17
|
+
endpoints, negation-aware predicates, coordinated verbs, clausal complements
|
|
18
|
+
and bounded sentence-scoped co-occurrence.
|
|
19
|
+
- Hybrid recall with a distance cutoff, configurable `RecallWeights` presets,
|
|
20
|
+
typed fact projection and an agent-readable `.mnemolite/AGENT_CONTEXT.md`
|
|
21
|
+
brief.
|
|
22
|
+
- MCP server exposing `add_memory`, `recall_memory`, `consolidate_memory`,
|
|
23
|
+
`delete_memory` and `decay_memory` over stdio.
|
|
24
|
+
- `mnemolite` Python package, `Mnemolite` API and `mnemolite-server` console
|
|
25
|
+
script.
|
|
26
|
+
- Agent Skills bundle at `skill/mnemolite-memory/` with workflows, memory
|
|
27
|
+
policy, examples, troubleshooting, MCP configuration and a connectivity
|
|
28
|
+
check.
|
|
29
|
+
- Packaging tests for the skill frontmatter, MCP config and a reproducibly
|
|
30
|
+
built archive.
|
|
31
|
+
|
|
32
|
+
### Changed
|
|
33
|
+
|
|
34
|
+
- Rebranded the distribution, import package, CLI, environment variables,
|
|
35
|
+
default database paths, brief directory, collection prefix and MCP server
|
|
36
|
+
name to Mnemolite.
|
|
37
|
+
- Dedupe is exact-only: a correction or paraphrase is stored as a separate
|
|
38
|
+
episode instead of being merged into stale text.
|
|
39
|
+
- Recall keeps generic query subjects such as `user` so user-centric graph
|
|
40
|
+
facts remain reachable.
|
|
41
|
+
- Triple endpoints share entity graph keys, including enclosing NER spans and
|
|
42
|
+
trailing-period normalization.
|
|
43
|
+
- The skill archive is generated from tracked source; it is no longer committed
|
|
44
|
+
to git.
|
|
45
|
+
|
|
46
|
+
### Fixed
|
|
47
|
+
|
|
48
|
+
- Near-duplicate dedupe no longer swallows corrections.
|
|
49
|
+
- Deleting an episode after decay no longer removes a fact still supported by
|
|
50
|
+
another episode.
|
|
51
|
+
- Repeated decay calls no longer compound.
|
|
52
|
+
- `co_occurs` edges can no longer crowd typed facts out of the graph result
|
|
53
|
+
limit.
|
|
54
|
+
- Typed facts are returned even when the vector index is empty or every episode
|
|
55
|
+
misses the distance cutoff.
|
|
56
|
+
- Pronoun and generic-noun subjects/objects no longer create `it`, `she`,
|
|
57
|
+
`corp.`, `project` or similar junk nodes.
|
|
58
|
+
|
|
59
|
+
### Packaging
|
|
60
|
+
|
|
61
|
+
- Distribution: `mnemolite`.
|
|
62
|
+
- Import: `mnemolite`; console script: `mnemolite-server`.
|
|
63
|
+
- Python: 3.10+.
|
|
64
|
+
- License: MIT.
|
|
65
|
+
- Project and skill URLs: `https://github.com/vdeem/mnemolite`.
|
|
66
|
+
- Build extras: `dev` for tests, `build` for release artifacts.
|
|
67
|
+
- Wheel and sdist are built with `python -m build`; the wheel contains the
|
|
68
|
+
server package and LICENSE, and the sdist contains the package, tests and
|
|
69
|
+
project documentation.
|
mnemolite-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
Copyright 2026 vdeem
|
|
2
|
+
|
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
4
|
+
|
|
5
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
6
|
+
|
|
7
|
+
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
mnemolite-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mnemolite
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Local-first, zero-LLM memory engine for AI agents
|
|
5
|
+
Author: vdeem
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/vdeem/mnemolite
|
|
8
|
+
Project-URL: Repository, https://github.com/vdeem/mnemolite
|
|
9
|
+
Project-URL: Documentation, https://github.com/vdeem/mnemolite/tree/main/docs
|
|
10
|
+
Project-URL: Issues, https://github.com/vdeem/mnemolite/issues
|
|
11
|
+
Keywords: ai,agents,memory,mcp,local-first,sqlite,chromadb
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: chromadb<2,>=1.5
|
|
24
|
+
Requires-Dist: sentence-transformers<7,>=3
|
|
25
|
+
Requires-Dist: spacy<4,>=3.7
|
|
26
|
+
Requires-Dist: mcp<3,>=2
|
|
27
|
+
Requires-Dist: anyio<5,>=4
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: pytest<10,>=8; extra == "dev"
|
|
30
|
+
Provides-Extra: build
|
|
31
|
+
Requires-Dist: build<2,>=1; extra == "build"
|
|
32
|
+
Requires-Dist: twine<7,>=5; extra == "build"
|
|
33
|
+
Requires-Dist: wheel<1,>=0.42; extra == "build"
|
|
34
|
+
Dynamic: license-file
|
|
35
|
+
|
|
36
|
+
# Mnemolite
|
|
37
|
+
|
|
38
|
+
A local-first, zero-LLM memory engine for AI agents.
|
|
39
|
+
|
|
40
|
+
## Why Mnemolite?
|
|
41
|
+
|
|
42
|
+
Most AI memory solutions (Mem0, Zep) use LLM calls on every message to extract facts. This is expensive, slow, and requires an API key.
|
|
43
|
+
|
|
44
|
+
Mnemolite takes a different approach: **cognitive consolidation**. It uses local NLP and embeddings to build a semantic knowledge graph entirely on your machine.
|
|
45
|
+
|
|
46
|
+
- **No API costs**
|
|
47
|
+
- **No data leaks**
|
|
48
|
+
- **No latency from external calls**
|
|
49
|
+
|
|
50
|
+
## Features
|
|
51
|
+
|
|
52
|
+
- **Zero-LLM Extraction** — spaCy NER plus dependency-based triples with lemmatized endpoints and negation-aware predicates (`not_like`, `is_not_a`) build the graph. No clustering, no second encoder, no OpenAI call, ever.
|
|
53
|
+
- **Multilingual by default** — Vectors come from `intfloat/multilingual-e5-small` (override with `MNEMOLITE_EMBED_MODEL`), so a Chinese query can recall an English memory. Extraction itself stays English-only via `en_core_web_sm`.
|
|
54
|
+
- **Hybrid Retrieval** — Combines vector similarity (episodic memory) with graph traversal (semantic memory).
|
|
55
|
+
- **Honest retrieval** — A `max_distance` threshold (0.5 by default, cosine >= 0.75) cuts weak matches, so "nothing relevant" is a valid answer instead of noise; typed facts are deduplicated and capped.
|
|
56
|
+
- **Local-First** — SQLite and ChromaDB on your disk.
|
|
57
|
+
- **Lightweight** — Runs on consumer hardware, no GPU required.
|
|
58
|
+
- **Forgetting (Decay)** — Old, unreinforced connections fade away and are archived, preventing database bloat and keeping only the most relevant memories.
|
|
59
|
+
- **Idempotent Consolidation** — Each episode is consolidated once; re-running `consolidate()` never inflates edge weights.
|
|
60
|
+
- **Crash-safe and forgetful** — Deleting an episode removes the facts only it supported, and a consolidation pass interrupted mid-way resumes without double-counting weights.
|
|
61
|
+
- **Agent brief** — After consolidation, Mnemolite writes `.mnemolite/AGENT_CONTEXT.md`, a human- and agent-readable summary of the current graph. Any agent (MCP or not) can read it at session start.
|
|
62
|
+
|
|
63
|
+
## Installation
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pip install mnemolite
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
From a checkout:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
pip install -e ".[dev]"
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The spaCy pipeline (`en_core_web_sm`) and the embedding model (`intfloat/multilingual-e5-small`) download automatically on first run. The first start therefore needs network access and enough disk space for the model cache.
|
|
76
|
+
|
|
77
|
+
## Quick Start
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from mnemolite.core import Mnemolite
|
|
81
|
+
|
|
82
|
+
# Initialize
|
|
83
|
+
mnemolite = Mnemolite(db_path="my_agent.db", chroma_path="./chroma_db")
|
|
84
|
+
|
|
85
|
+
# 1. Add memories (episodic layer)
|
|
86
|
+
episode_id = mnemolite.add("Alice is a software engineer based in London.")
|
|
87
|
+
mnemolite.add("Bob is working on a project using PyTorch.")
|
|
88
|
+
|
|
89
|
+
# 2. Consolidate (builds the graph; only new episodes are processed)
|
|
90
|
+
mnemolite.consolidate()
|
|
91
|
+
|
|
92
|
+
# 3. Recall (hybrid search)
|
|
93
|
+
results = mnemolite.recall("What technologies is Bob using?")
|
|
94
|
+
|
|
95
|
+
print(results["episodes"]) # Raw texts from vector search
|
|
96
|
+
print(results["facts"]) # Graph relations (Bob -> pytorch)
|
|
97
|
+
|
|
98
|
+
# 4. Tighten recall: drop anything past the distance cutoff
|
|
99
|
+
# (0.5 squared-L2 = cosine 0.75 on normalized embeddings)
|
|
100
|
+
results = mnemolite.recall("What technologies is Bob using?", k=3, max_distance=0.5)
|
|
101
|
+
|
|
102
|
+
# 5. Delete a memory (episode, vector and its graph contributions)
|
|
103
|
+
mnemolite.delete([episode_id])
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## MCP server
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
python -m mnemolite.server
|
|
110
|
+
# or, after an editable install:
|
|
111
|
+
mnemolite-server
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The server exposes `add_memory`, `recall_memory`, `consolidate_memory`,
|
|
115
|
+
`delete_memory` and `decay_memory` over stdio. It opens the store in an MCP
|
|
116
|
+
lifespan and closes Chroma on shutdown.
|
|
117
|
+
|
|
118
|
+
By default the store lives in the checkout root (when running from a checkout)
|
|
119
|
+
or `~/.mnemolite`; override it with `MNEMOLITE_DATA_DIR`, `MNEMOLITE_DB_PATH` or
|
|
120
|
+
`MNEMOLITE_CHROMA_PATH`. This keeps the memory location independent of the
|
|
121
|
+
directory the MCP client launches the server from.
|
|
122
|
+
|
|
123
|
+
## Agent skill
|
|
124
|
+
|
|
125
|
+
`skill/mnemolite-memory/` is a self-contained Agent Skills package that
|
|
126
|
+
teaches an agent when and how to call the Mnemolite MCP tools. Build the
|
|
127
|
+
upload-ready archive from that directory with the command in
|
|
128
|
+
[docs/skill.md](docs/skill.md); the ZIP is a generated artifact and is not
|
|
129
|
+
committed.
|
|
130
|
+
|
|
131
|
+
- Packaging contract and release checklist: [docs/skill.md](docs/skill.md).
|
|
132
|
+
- The skill requires the `mnemolite` package (or an editable checkout)
|
|
133
|
+
and a running `mnemolite-server` over stdio.
|
|
134
|
+
- No external LLM API is called by the server or the skill.
|
|
135
|
+
|
|
136
|
+
## How it works
|
|
137
|
+
|
|
138
|
+
1. **Episodic Memory** — Raw texts are embedded with `intfloat/multilingual-e5-small` and stored in ChromaDB.
|
|
139
|
+
2. **Semantic Memory** — Consolidation processes only episodes it has not seen yet (`consolidated_at`), extracts entities and triples with spaCy, and builds a weighted graph in SQLite.
|
|
140
|
+
3. **Retrieval** — A query triggers a vector search filtered by `max_distance` (with salience and recency as small tie-breakers) plus a graph lookup, giving the agent both the original context and structured facts. Vectors whose episode row no longer exists are ignored and pruned at startup.
|
|
141
|
+
4. **Deletion & durability** — `delete()` removes the episode, its vectors and its recorded edge contributions; edges still supported by other episodes remain. Each consolidation pass marks episodes inside their write transaction, so a crash resumes instead of inflating weights.
|
|
142
|
+
|
|
143
|
+
## Roadmap
|
|
144
|
+
|
|
145
|
+
- [x] Core memory engine (episodic + semantic)
|
|
146
|
+
- [x] Zero-LLM consolidation
|
|
147
|
+
- [x] Decay & forgetting algorithm
|
|
148
|
+
- [x] MCP (Model Context Protocol) server
|
|
149
|
+
- [x] Multilingual embeddings (`intfloat/multilingual-e5-small`)
|
|
150
|
+
- [~] Multi-language support — partial: retrieval is multilingual, spaCy extraction is still English-only
|
|
151
|
+
- [x] Phase 2 — Agent context brief
|
|
152
|
+
- [x] Reliability hardening and negation-aware extraction
|
|
153
|
+
- [x] MCP server hardening and graph lifecycle
|
|
154
|
+
- [x] Packaging, CI and hermetic MCP smoke
|
|
155
|
+
- [x] Agent skill package and installable distribution
|
|
156
|
+
- [ ] Phase 2b — RAG adapters
|
|
157
|
+
|
|
158
|
+
See [docs/status.md](docs/status.md) for the current status, recent changes and the detailed roadmap, and [docs/extraction.md](docs/extraction.md) for the extraction rules. Release notes are in [CHANGELOG.md](CHANGELOG.md).
|
|
159
|
+
|
|
160
|
+
## License
|
|
161
|
+
|
|
162
|
+
MIT
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# Mnemolite
|
|
2
|
+
|
|
3
|
+
A local-first, zero-LLM memory engine for AI agents.
|
|
4
|
+
|
|
5
|
+
## Why Mnemolite?
|
|
6
|
+
|
|
7
|
+
Most AI memory solutions (Mem0, Zep) use LLM calls on every message to extract facts. This is expensive, slow, and requires an API key.
|
|
8
|
+
|
|
9
|
+
Mnemolite takes a different approach: **cognitive consolidation**. It uses local NLP and embeddings to build a semantic knowledge graph entirely on your machine.
|
|
10
|
+
|
|
11
|
+
- **No API costs**
|
|
12
|
+
- **No data leaks**
|
|
13
|
+
- **No latency from external calls**
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
|
|
17
|
+
- **Zero-LLM Extraction** — spaCy NER plus dependency-based triples with lemmatized endpoints and negation-aware predicates (`not_like`, `is_not_a`) build the graph. No clustering, no second encoder, no OpenAI call, ever.
|
|
18
|
+
- **Multilingual by default** — Vectors come from `intfloat/multilingual-e5-small` (override with `MNEMOLITE_EMBED_MODEL`), so a Chinese query can recall an English memory. Extraction itself stays English-only via `en_core_web_sm`.
|
|
19
|
+
- **Hybrid Retrieval** — Combines vector similarity (episodic memory) with graph traversal (semantic memory).
|
|
20
|
+
- **Honest retrieval** — A `max_distance` threshold (0.5 by default, cosine >= 0.75) cuts weak matches, so "nothing relevant" is a valid answer instead of noise; typed facts are deduplicated and capped.
|
|
21
|
+
- **Local-First** — SQLite and ChromaDB on your disk.
|
|
22
|
+
- **Lightweight** — Runs on consumer hardware, no GPU required.
|
|
23
|
+
- **Forgetting (Decay)** — Old, unreinforced connections fade away and are archived, preventing database bloat and keeping only the most relevant memories.
|
|
24
|
+
- **Idempotent Consolidation** — Each episode is consolidated once; re-running `consolidate()` never inflates edge weights.
|
|
25
|
+
- **Crash-safe and forgetful** — Deleting an episode removes the facts only it supported, and a consolidation pass interrupted mid-way resumes without double-counting weights.
|
|
26
|
+
- **Agent brief** — After consolidation, Mnemolite writes `.mnemolite/AGENT_CONTEXT.md`, a human- and agent-readable summary of the current graph. Any agent (MCP or not) can read it at session start.
|
|
27
|
+
|
|
28
|
+
## Installation
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pip install mnemolite
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
From a checkout:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install -e ".[dev]"
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The spaCy pipeline (`en_core_web_sm`) and the embedding model (`intfloat/multilingual-e5-small`) download automatically on first run. The first start therefore needs network access and enough disk space for the model cache.
|
|
41
|
+
|
|
42
|
+
## Quick Start
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
from mnemolite.core import Mnemolite
|
|
46
|
+
|
|
47
|
+
# Initialize
|
|
48
|
+
mnemolite = Mnemolite(db_path="my_agent.db", chroma_path="./chroma_db")
|
|
49
|
+
|
|
50
|
+
# 1. Add memories (episodic layer)
|
|
51
|
+
episode_id = mnemolite.add("Alice is a software engineer based in London.")
|
|
52
|
+
mnemolite.add("Bob is working on a project using PyTorch.")
|
|
53
|
+
|
|
54
|
+
# 2. Consolidate (builds the graph; only new episodes are processed)
|
|
55
|
+
mnemolite.consolidate()
|
|
56
|
+
|
|
57
|
+
# 3. Recall (hybrid search)
|
|
58
|
+
results = mnemolite.recall("What technologies is Bob using?")
|
|
59
|
+
|
|
60
|
+
print(results["episodes"]) # Raw texts from vector search
|
|
61
|
+
print(results["facts"]) # Graph relations (Bob -> pytorch)
|
|
62
|
+
|
|
63
|
+
# 4. Tighten recall: drop anything past the distance cutoff
|
|
64
|
+
# (0.5 squared-L2 = cosine 0.75 on normalized embeddings)
|
|
65
|
+
results = mnemolite.recall("What technologies is Bob using?", k=3, max_distance=0.5)
|
|
66
|
+
|
|
67
|
+
# 5. Delete a memory (episode, vector and its graph contributions)
|
|
68
|
+
mnemolite.delete([episode_id])
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## MCP server
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
python -m mnemolite.server
|
|
75
|
+
# or, after an editable install:
|
|
76
|
+
mnemolite-server
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The server exposes `add_memory`, `recall_memory`, `consolidate_memory`,
|
|
80
|
+
`delete_memory` and `decay_memory` over stdio. It opens the store in an MCP
|
|
81
|
+
lifespan and closes Chroma on shutdown.
|
|
82
|
+
|
|
83
|
+
By default the store lives in the checkout root (when running from a checkout)
|
|
84
|
+
or `~/.mnemolite`; override it with `MNEMOLITE_DATA_DIR`, `MNEMOLITE_DB_PATH` or
|
|
85
|
+
`MNEMOLITE_CHROMA_PATH`. This keeps the memory location independent of the
|
|
86
|
+
directory the MCP client launches the server from.
|
|
87
|
+
|
|
88
|
+
## Agent skill
|
|
89
|
+
|
|
90
|
+
`skill/mnemolite-memory/` is a self-contained Agent Skills package that
|
|
91
|
+
teaches an agent when and how to call the Mnemolite MCP tools. Build the
|
|
92
|
+
upload-ready archive from that directory with the command in
|
|
93
|
+
[docs/skill.md](docs/skill.md); the ZIP is a generated artifact and is not
|
|
94
|
+
committed.
|
|
95
|
+
|
|
96
|
+
- Packaging contract and release checklist: [docs/skill.md](docs/skill.md).
|
|
97
|
+
- The skill requires the `mnemolite` package (or an editable checkout)
|
|
98
|
+
and a running `mnemolite-server` over stdio.
|
|
99
|
+
- No external LLM API is called by the server or the skill.
|
|
100
|
+
|
|
101
|
+
## How it works
|
|
102
|
+
|
|
103
|
+
1. **Episodic Memory** — Raw texts are embedded with `intfloat/multilingual-e5-small` and stored in ChromaDB.
|
|
104
|
+
2. **Semantic Memory** — Consolidation processes only episodes it has not seen yet (`consolidated_at`), extracts entities and triples with spaCy, and builds a weighted graph in SQLite.
|
|
105
|
+
3. **Retrieval** — A query triggers a vector search filtered by `max_distance` (with salience and recency as small tie-breakers) plus a graph lookup, giving the agent both the original context and structured facts. Vectors whose episode row no longer exists are ignored and pruned at startup.
|
|
106
|
+
4. **Deletion & durability** — `delete()` removes the episode, its vectors and its recorded edge contributions; edges still supported by other episodes remain. Each consolidation pass marks episodes inside their write transaction, so a crash resumes instead of inflating weights.
|
|
107
|
+
|
|
108
|
+
## Roadmap
|
|
109
|
+
|
|
110
|
+
- [x] Core memory engine (episodic + semantic)
|
|
111
|
+
- [x] Zero-LLM consolidation
|
|
112
|
+
- [x] Decay & forgetting algorithm
|
|
113
|
+
- [x] MCP (Model Context Protocol) server
|
|
114
|
+
- [x] Multilingual embeddings (`intfloat/multilingual-e5-small`)
|
|
115
|
+
- [~] Multi-language support — partial: retrieval is multilingual, spaCy extraction is still English-only
|
|
116
|
+
- [x] Phase 2 — Agent context brief
|
|
117
|
+
- [x] Reliability hardening and negation-aware extraction
|
|
118
|
+
- [x] MCP server hardening and graph lifecycle
|
|
119
|
+
- [x] Packaging, CI and hermetic MCP smoke
|
|
120
|
+
- [x] Agent skill package and installable distribution
|
|
121
|
+
- [ ] Phase 2b — RAG adapters
|
|
122
|
+
|
|
123
|
+
See [docs/status.md](docs/status.md) for the current status, recent changes and the detailed roadmap, and [docs/extraction.md](docs/extraction.md) for the extraction rules. Release notes are in [CHANGELOG.md](CHANGELOG.md).
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
MIT
|