semantic-memory-mcp 1.0.2__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.
Files changed (12) hide show
  1. semantic_memory_mcp-1.0.2/LICENSE +21 -0
  2. semantic_memory_mcp-1.0.2/PKG-INFO +135 -0
  3. semantic_memory_mcp-1.0.2/README.md +117 -0
  4. semantic_memory_mcp-1.0.2/memory_server.py +1147 -0
  5. semantic_memory_mcp-1.0.2/pyproject.toml +29 -0
  6. semantic_memory_mcp-1.0.2/semantic_memory_mcp.egg-info/PKG-INFO +135 -0
  7. semantic_memory_mcp-1.0.2/semantic_memory_mcp.egg-info/SOURCES.txt +10 -0
  8. semantic_memory_mcp-1.0.2/semantic_memory_mcp.egg-info/dependency_links.txt +1 -0
  9. semantic_memory_mcp-1.0.2/semantic_memory_mcp.egg-info/entry_points.txt +2 -0
  10. semantic_memory_mcp-1.0.2/semantic_memory_mcp.egg-info/requires.txt +6 -0
  11. semantic_memory_mcp-1.0.2/semantic_memory_mcp.egg-info/top_level.txt +1 -0
  12. semantic_memory_mcp-1.0.2/setup.cfg +4 -0
semantic_memory_mcp-1.0.2/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Michael Logies
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
semantic_memory_mcp-1.0.2/PKG-INFO ADDED
@@ -0,0 +1,135 @@
1
+ Metadata-Version: 2.4
2
+ Name: semantic-memory-mcp
3
+ Version: 1.0.2
4
+ Summary: Single-file, self-hosted semantic memory MCP server for AI coding agents
5
+ Author: Michael Logies
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Michael-Logies/semantic-memory-mcp
8
+ Requires-Python: >=3.11
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Requires-Dist: fastmcp==3.4.7
12
+ Requires-Dist: onnxruntime==1.29.0
13
+ Requires-Dist: sqlite-vec==0.1.9
14
+ Requires-Dist: huggingface_hub==1.28.0
15
+ Requires-Dist: tokenizers==0.23.1
16
+ Requires-Dist: numpy==2.5.2
17
+ Dynamic: license-file
18
+
19
+ # Semantic Memory MCP
20
+
21
+ **Persistent, semantic memory for AI coding agents — a single Python file, entirely local.**
22
+
23
+ `semantic-memory-mcp` is a self-hosted [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI coding agents a durable, searchable memory across sessions. It is built as one Python file, stores everything in a single local SQLite database, and needs no cloud service and no API key.
24
+
25
+ ## What it is
26
+
27
+ - **Cross-session memory:** notes survive between sessions; the agent searches its own memory at the start of every task instead of relying on the user to re-explain context.
28
+ - **Hybrid retrieval:** keyword full-text search (SQLite FTS5) and semantic vector search (sqlite-vec) are combined through Reciprocal Rank Fusion — a note can be found by exact wording *or* by meaning.
29
+ - **Multilingual embeddings:** quantized ONNX model (`Xenova/multilingual-e5-small`, ~113 MB) runs locally on CPU. English and German work equally well; no OpenAI key required.
30
+ - **Trivially auditable:** the whole server is a single readable file (`memory_server.py`, ~1,100 lines). There is no hidden state beyond the SQLite file.
31
+
32
+ ### Tools
33
+
34
+ | Tool | Purpose |
35
+ |------|---------|
36
+ | `memory_store` | Save a note (with tags and source) |
37
+ | `memory_search` | Hybrid search (semantic + full-text), optional token budget |
38
+ | `memory_get` / `memory_recent` | Read one note by ID / list recent notes |
39
+ | `memory_update` / `memory_delete` | Edit or remove a note |
40
+ | `memory_status` | Database statistics |
41
+ | `memory_zotero_sync` | Optional: back up memory content into a Zotero library |
42
+
43
+ ## Why
44
+
45
+ AI coding agents forget everything between sessions. File-based memory (markdown indexes that get reloaded) is keyword-based: it has no semantic recall and no ranking — a note saved as *"embedding model comparison"* will not be found when the agent later asks *"which embedding did we test?"*.
46
+
47
+ This server was built as a working reference implementation and **measured, not assumed** — see [Evaluation](#evaluation).
48
+
49
+ ## Evaluation
50
+
51
+ Retrieval quality was tracked throughout development. Recall@5 — the share of queries where the correct note is among the top 5 hits — rose from **68.4 % to 89.2 %** across successive, individually measured optimization steps (chunking, embedding model choice, query rewriting, and more). The full measurement series with a 22-study comparison table is documented here:
52
+
53
+ **[The Memory Server in the Lab](https://www.logies.de/memory-server-research.html)**
54
+
55
+ ## Working across parallel sessions
56
+
57
+ You can run several agent sessions at the same time — they all share one memory. Instead of a single "where did I stop?" slot that parallel sessions would overwrite, each session ends its work with a short **checkpoint note** in the memory (topic, what was done, what is open, next step), with the writing agent and model recorded in the `source` field. Asking any window *"Where did we stop on X?"* then finds the answer — even if the work happened in a different window. The convention is part of the agent rules (`memory-mcp-knowledge.md`, R17).
58
+
59
+ ## Installation
60
+
61
+ **Prerequisites:** Linux, Python 3.11+ with `venv`, ~500 MB free disk space (virtual environment plus embedding model). The server is written for Linux, but not limited to it: since everything is one Python file, any AI assistant can read the script and adapt the installation for Windows or macOS.
62
+
63
+ ```bash
64
+ git clone https://github.com/Michael-Logies/semantic-memory-mcp.git
65
+ cd semantic-memory-mcp
66
+ bash setup.sh # creates the venv, installs dependencies, downloads the model
67
+ bash verify.sh # checks the installation, writes a report
68
+ ```
69
+
70
+ The embedding model is downloaded automatically from Hugging Face (`huggingface_hub`, no account needed).
71
+
72
+ **Alternative: pip install from GitHub** — no clone needed; the package ships a `semantic-memory-mcp` command, and the embedding model (~113 MB) downloads automatically on first start:
73
+
74
+ ```bash
75
+ python3 -m venv ~/.venv-memory
76
+ ~/.venv-memory/bin/pip install git+https://github.com/Michael-Logies/semantic-memory-mcp.git
77
+ ```
78
+
79
+ Then register the server in your AI agent's MCP configuration (example for Qwen Code, `~/.qwen/settings.json`):
80
+
81
+ ```json
82
+ {
83
+ "mcpServers": {
84
+ "memory": {
85
+ "command": "/home/<user>/.venv-memory/bin/python3",
86
+ "args": ["/path/to/semantic-memory-mcp/memory_server.py"],
87
+ "transport": "stdio"
88
+ }
89
+ }
90
+ }
91
+ ```
92
+
93
+ If your client has an `mcp add` command, registration is a one-liner once the venv exists (with the pip installation, use the packaged `~/.venv-memory/bin/semantic-memory-mcp` as the single command instead of `python3 …/memory_server.py`):
94
+
95
+ ```bash
96
+ # Qwen Code (note: no `--` separator)
97
+ qwen mcp add memory ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py
98
+
99
+ # Claude Code
100
+ claude mcp add memory -- ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py
101
+
102
+ # Codex CLI
103
+ codex mcp add memory -- ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py
104
+ ```
105
+
106
+ The Qwen Code and Claude Code commands were verified against the locally installed CLIs. The **Codex line was not tested by us** — its syntax was adopted from the documentation of other projects, since we only use Qwen Code ourselves.
107
+
108
+ See `mcp-config.json` for a template. `usage-notes.md` contains practical guidance for working with an agent that has persistent memory (context management, what to store, tagging, parallel sessions); the German version ships as `nutzungshinweise.md`.
109
+
110
+ ## Documentation for your AI agent
111
+
112
+ Two documents ship with this repository, written for the agent rather than the human (both CC0-licensed):
113
+
114
+ - **`memory-mcp-knowledge.md`** — the rules and learning protocol for operating the memory server in daily agent work: when to read, when to write, what to store, and how to tag it.
115
+ - **`zotero-mcp-agent-knowledge.md`** — hard-won knowledge about connecting Zotero with AI agents via MCP servers: tool comparison (zotero-mcp-server, Zoteus, pyzotero, CLI access), benchmarks, and best practices. Since 31 August 2026, **Zoteus** is the sole Zotero MCP server in the reference setup; the older ChromaDB-based material is kept as background, not as a recommendation.
116
+
117
+ ## The bigger picture
118
+
119
+ This server is the memory layer of a reproducible **AI workstation for students** — a complete setup guide (research, learning, literature work on a Linux machine) documented step by step here:
120
+
121
+ - **[AI Workstation for Students: Research, Learning, and More](https://www.logies.de/ai-workstation-linux-vm.html)** (English)
122
+ - **[KI-Arbeitsplatz fürs Studium: Recherche, Lernen und mehr](https://www.logies.de/studienarbeitsplatz-linux-vm.html)** (German)
123
+
124
+ Memory comes in two layers in that setup: this server stores the *working memory* of day-to-day collaboration with the agent, while scholarly literature lives in a Zotero research database made searchable by meaning through a second MCP server ([Zoteus](https://github.com/oscardvs/zoteus)). How the two fit together is described on the project pages:
125
+
126
+ - [Cross-Session Memory for AI Agents](https://www.logies.de/memory-mcp-for-ai-agents.html) (English)
127
+ - [Cross-Session-Memory für KI-Agenten](https://www.logies.de/memory-mcp-fuer-ki-agenten.html) (German)
128
+
129
+ ## Status and maintenance
130
+
131
+ The server has been in daily production use since August 2026 as the memory of a working AI workstation. It is developed and maintained by [Michael Logies](https://github.com/Michael-Logies) in close collaboration with AI coding agents — see the project pages above for how it was built and evaluated. The server is provided **as-is**: bug reports are welcome and handled on a best-effort basis, but there is no formal support.
132
+
133
+ ## License
134
+
135
+ MIT — see [LICENSE](LICENSE).
semantic_memory_mcp-1.0.2/README.md ADDED
@@ -0,0 +1,117 @@
1
+ # Semantic Memory MCP
2
+
3
+ **Persistent, semantic memory for AI coding agents — a single Python file, entirely local.**
4
+
5
+ `semantic-memory-mcp` is a self-hosted [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI coding agents a durable, searchable memory across sessions. It is built as one Python file, stores everything in a single local SQLite database, and needs no cloud service and no API key.
6
+
7
+ ## What it is
8
+
9
+ - **Cross-session memory:** notes survive between sessions; the agent searches its own memory at the start of every task instead of relying on the user to re-explain context.
10
+ - **Hybrid retrieval:** keyword full-text search (SQLite FTS5) and semantic vector search (sqlite-vec) are combined through Reciprocal Rank Fusion — a note can be found by exact wording *or* by meaning.
11
+ - **Multilingual embeddings:** quantized ONNX model (`Xenova/multilingual-e5-small`, ~113 MB) runs locally on CPU. English and German work equally well; no OpenAI key required.
12
+ - **Trivially auditable:** the whole server is a single readable file (`memory_server.py`, ~1,100 lines). There is no hidden state beyond the SQLite file.
13
+
14
+ ### Tools
15
+
16
+ | Tool | Purpose |
17
+ |------|---------|
18
+ | `memory_store` | Save a note (with tags and source) |
19
+ | `memory_search` | Hybrid search (semantic + full-text), optional token budget |
20
+ | `memory_get` / `memory_recent` | Read one note by ID / list recent notes |
21
+ | `memory_update` / `memory_delete` | Edit or remove a note |
22
+ | `memory_status` | Database statistics |
23
+ | `memory_zotero_sync` | Optional: back up memory content into a Zotero library |
24
+
25
+ ## Why
26
+
27
+ AI coding agents forget everything between sessions. File-based memory (markdown indexes that get reloaded) is keyword-based: it has no semantic recall and no ranking — a note saved as *"embedding model comparison"* will not be found when the agent later asks *"which embedding did we test?"*.
28
+
29
+ This server was built as a working reference implementation and **measured, not assumed** — see [Evaluation](#evaluation).
30
+
31
+ ## Evaluation
32
+
33
+ Retrieval quality was tracked throughout development. Recall@5 — the share of queries where the correct note is among the top 5 hits — rose from **68.4 % to 89.2 %** across successive, individually measured optimization steps (chunking, embedding model choice, query rewriting, and more). The full measurement series with a 22-study comparison table is documented here:
34
+
35
+ **[The Memory Server in the Lab](https://www.logies.de/memory-server-research.html)**
36
+
37
+ ## Working across parallel sessions
38
+
39
+ You can run several agent sessions at the same time — they all share one memory. Instead of a single "where did I stop?" slot that parallel sessions would overwrite, each session ends its work with a short **checkpoint note** in the memory (topic, what was done, what is open, next step), with the writing agent and model recorded in the `source` field. Asking any window *"Where did we stop on X?"* then finds the answer — even if the work happened in a different window. The convention is part of the agent rules (`memory-mcp-knowledge.md`, R17).
40
+
41
+ ## Installation
42
+
43
+ **Prerequisites:** Linux, Python 3.11+ with `venv`, ~500 MB free disk space (virtual environment plus embedding model). The server is written for Linux, but not limited to it: since everything is one Python file, any AI assistant can read the script and adapt the installation for Windows or macOS.
44
+
45
+ ```bash
46
+ git clone https://github.com/Michael-Logies/semantic-memory-mcp.git
47
+ cd semantic-memory-mcp
48
+ bash setup.sh # creates the venv, installs dependencies, downloads the model
49
+ bash verify.sh # checks the installation, writes a report
50
+ ```
51
+
52
+ The embedding model is downloaded automatically from Hugging Face (`huggingface_hub`, no account needed).
53
+
54
+ **Alternative: pip install from GitHub** — no clone needed; the package ships a `semantic-memory-mcp` command, and the embedding model (~113 MB) downloads automatically on first start:
55
+
56
+ ```bash
57
+ python3 -m venv ~/.venv-memory
58
+ ~/.venv-memory/bin/pip install git+https://github.com/Michael-Logies/semantic-memory-mcp.git
59
+ ```
60
+
61
+ Then register the server in your AI agent's MCP configuration (example for Qwen Code, `~/.qwen/settings.json`):
62
+
63
+ ```json
64
+ {
65
+ "mcpServers": {
66
+ "memory": {
67
+ "command": "/home/<user>/.venv-memory/bin/python3",
68
+ "args": ["/path/to/semantic-memory-mcp/memory_server.py"],
69
+ "transport": "stdio"
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ If your client has an `mcp add` command, registration is a one-liner once the venv exists (with the pip installation, use the packaged `~/.venv-memory/bin/semantic-memory-mcp` as the single command instead of `python3 …/memory_server.py`):
76
+
77
+ ```bash
78
+ # Qwen Code (note: no `--` separator)
79
+ qwen mcp add memory ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py
80
+
81
+ # Claude Code
82
+ claude mcp add memory -- ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py
83
+
84
+ # Codex CLI
85
+ codex mcp add memory -- ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py
86
+ ```
87
+
88
+ The Qwen Code and Claude Code commands were verified against the locally installed CLIs. The **Codex line was not tested by us** — its syntax was adopted from the documentation of other projects, since we only use Qwen Code ourselves.
89
+
90
+ See `mcp-config.json` for a template. `usage-notes.md` contains practical guidance for working with an agent that has persistent memory (context management, what to store, tagging, parallel sessions); the German version ships as `nutzungshinweise.md`.
91
+
92
+ ## Documentation for your AI agent
93
+
94
+ Two documents ship with this repository, written for the agent rather than the human (both CC0-licensed):
95
+
96
+ - **`memory-mcp-knowledge.md`** — the rules and learning protocol for operating the memory server in daily agent work: when to read, when to write, what to store, and how to tag it.
97
+ - **`zotero-mcp-agent-knowledge.md`** — hard-won knowledge about connecting Zotero with AI agents via MCP servers: tool comparison (zotero-mcp-server, Zoteus, pyzotero, CLI access), benchmarks, and best practices. Since 31 August 2026, **Zoteus** is the sole Zotero MCP server in the reference setup; the older ChromaDB-based material is kept as background, not as a recommendation.
98
+
99
+ ## The bigger picture
100
+
101
+ This server is the memory layer of a reproducible **AI workstation for students** — a complete setup guide (research, learning, literature work on a Linux machine) documented step by step here:
102
+
103
+ - **[AI Workstation for Students: Research, Learning, and More](https://www.logies.de/ai-workstation-linux-vm.html)** (English)
104
+ - **[KI-Arbeitsplatz fürs Studium: Recherche, Lernen und mehr](https://www.logies.de/studienarbeitsplatz-linux-vm.html)** (German)
105
+
106
+ Memory comes in two layers in that setup: this server stores the *working memory* of day-to-day collaboration with the agent, while scholarly literature lives in a Zotero research database made searchable by meaning through a second MCP server ([Zoteus](https://github.com/oscardvs/zoteus)). How the two fit together is described on the project pages:
107
+
108
+ - [Cross-Session Memory for AI Agents](https://www.logies.de/memory-mcp-for-ai-agents.html) (English)
109
+ - [Cross-Session-Memory für KI-Agenten](https://www.logies.de/memory-mcp-fuer-ki-agenten.html) (German)
110
+
111
+ ## Status and maintenance
112
+
113
+ The server has been in daily production use since August 2026 as the memory of a working AI workstation. It is developed and maintained by [Michael Logies](https://github.com/Michael-Logies) in close collaboration with AI coding agents — see the project pages above for how it was built and evaluated. The server is provided **as-is**: bug reports are welcome and handled on a best-effort basis, but there is no formal support.
114
+
115
+ ## License
116
+
117
+ MIT — see [LICENSE](LICENSE).