orimem-mcp 0.1.1__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 (68) hide show
  1. orimem_mcp-0.1.1/LICENSE +21 -0
  2. orimem_mcp-0.1.1/PKG-INFO +263 -0
  3. orimem_mcp-0.1.1/README.md +224 -0
  4. orimem_mcp-0.1.1/pyproject.toml +57 -0
  5. orimem_mcp-0.1.1/setup.cfg +4 -0
  6. orimem_mcp-0.1.1/src/orimem/__init__.py +1 -0
  7. orimem_mcp-0.1.1/src/orimem/__main__.py +4 -0
  8. orimem_mcp-0.1.1/src/orimem/adapters/__init__.py +431 -0
  9. orimem_mcp-0.1.1/src/orimem/capture/__init__.py +110 -0
  10. orimem_mcp-0.1.1/src/orimem/capture/claude.py +150 -0
  11. orimem_mcp-0.1.1/src/orimem/capture/codex.py +116 -0
  12. orimem_mcp-0.1.1/src/orimem/capture/common.py +145 -0
  13. orimem_mcp-0.1.1/src/orimem/capture/dsh.py +153 -0
  14. orimem_mcp-0.1.1/src/orimem/capture/worker.py +24 -0
  15. orimem_mcp-0.1.1/src/orimem/cli.py +342 -0
  16. orimem_mcp-0.1.1/src/orimem/config.py +197 -0
  17. orimem_mcp-0.1.1/src/orimem/core/__init__.py +3 -0
  18. orimem_mcp-0.1.1/src/orimem/core/assessment_revision.py +147 -0
  19. orimem_mcp-0.1.1/src/orimem/core/backend.py +925 -0
  20. orimem_mcp-0.1.1/src/orimem/core/candidate_reviews.py +154 -0
  21. orimem_mcp-0.1.1/src/orimem/core/content_policy.py +19 -0
  22. orimem_mcp-0.1.1/src/orimem/core/continuous.py +202 -0
  23. orimem_mcp-0.1.1/src/orimem/core/corrections.py +265 -0
  24. orimem_mcp-0.1.1/src/orimem/core/embedding.py +189 -0
  25. orimem_mcp-0.1.1/src/orimem/core/evidence_context.py +143 -0
  26. orimem_mcp-0.1.1/src/orimem/core/evidence_pack.py +56 -0
  27. orimem_mcp-0.1.1/src/orimem/core/history.py +288 -0
  28. orimem_mcp-0.1.1/src/orimem/core/knowledge_index.py +187 -0
  29. orimem_mcp-0.1.1/src/orimem/core/lifecycle.py +729 -0
  30. orimem_mcp-0.1.1/src/orimem/core/markdown.py +123 -0
  31. orimem_mcp-0.1.1/src/orimem/core/mcp_server.py +362 -0
  32. orimem_mcp-0.1.1/src/orimem/core/message_sources.py +54 -0
  33. orimem_mcp-0.1.1/src/orimem/core/migration.py +466 -0
  34. orimem_mcp-0.1.1/src/orimem/core/pending_index.py +212 -0
  35. orimem_mcp-0.1.1/src/orimem/core/privacy.py +129 -0
  36. orimem_mcp-0.1.1/src/orimem/core/records.py +144 -0
  37. orimem_mcp-0.1.1/src/orimem/core/retrieval_policy.py +177 -0
  38. orimem_mcp-0.1.1/src/orimem/core/service.py +178 -0
  39. orimem_mcp-0.1.1/src/orimem/core/source_index.py +113 -0
  40. orimem_mcp-0.1.1/src/orimem/core/source_stage.py +144 -0
  41. orimem_mcp-0.1.1/src/orimem/core/stage_jobs.py +155 -0
  42. orimem_mcp-0.1.1/src/orimem/core/task_context.py +501 -0
  43. orimem_mcp-0.1.1/src/orimem/core/watcher.py +98 -0
  44. orimem_mcp-0.1.1/src/orimem/daily.py +113 -0
  45. orimem_mcp-0.1.1/src/orimem/hook.py +122 -0
  46. orimem_mcp-0.1.1/src/orimem/hook_entry.py +106 -0
  47. orimem_mcp-0.1.1/src/orimem/journal_state.py +487 -0
  48. orimem_mcp-0.1.1/src/orimem/journal_writer.py +465 -0
  49. orimem_mcp-0.1.1/src/orimem/lifecycle_ctl.py +24 -0
  50. orimem_mcp-0.1.1/src/orimem/model.py +140 -0
  51. orimem_mcp-0.1.1/src/orimem/skill/orimem/SKILL.md +34 -0
  52. orimem_mcp-0.1.1/src/orimem/skill/orimem/agents/openai.yaml +3 -0
  53. orimem_mcp-0.1.1/src/orimem/skill/orimem/references/automatic-journaling.md +111 -0
  54. orimem_mcp-0.1.1/src/orimem/skill/orimem/references/history.md +37 -0
  55. orimem_mcp-0.1.1/src/orimem/skill/orimem/references/lifecycle.md +91 -0
  56. orimem_mcp-0.1.1/src/orimem/skill/orimem/references/maintenance.md +18 -0
  57. orimem_mcp-0.1.1/src/orimem/skill/orimem/references/organizing.md +86 -0
  58. orimem_mcp-0.1.1/src/orimem/skill/orimem/references/retrieval.md +61 -0
  59. orimem_mcp-0.1.1/src/orimem/templates/vault/AGENTS.md +24 -0
  60. orimem_mcp-0.1.1/src/orimem_mcp.egg-info/PKG-INFO +263 -0
  61. orimem_mcp-0.1.1/src/orimem_mcp.egg-info/SOURCES.txt +66 -0
  62. orimem_mcp-0.1.1/src/orimem_mcp.egg-info/dependency_links.txt +1 -0
  63. orimem_mcp-0.1.1/src/orimem_mcp.egg-info/entry_points.txt +2 -0
  64. orimem_mcp-0.1.1/src/orimem_mcp.egg-info/requires.txt +15 -0
  65. orimem_mcp-0.1.1/src/orimem_mcp.egg-info/top_level.txt +1 -0
  66. orimem_mcp-0.1.1/tests/test_capture.py +87 -0
  67. orimem_mcp-0.1.1/tests/test_config_adapters.py +180 -0
  68. orimem_mcp-0.1.1/tests/test_release.py +35 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Orion
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.
@@ -0,0 +1,263 @@
1
+ Metadata-Version: 2.4
2
+ Name: orimem-mcp
3
+ Version: 0.1.1
4
+ Summary: Local Obsidian-vault memory for coding agents (Claude Code, Codex, DeepSeek Harness) over MCP: hybrid recall, verified write-back, conversation capture and daily summaries.
5
+ Author: Orion
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/Wen5555/OriMem
8
+ Project-URL: Documentation, https://github.com/Wen5555/OriMem#readme
9
+ Project-URL: Issues, https://github.com/Wen5555/OriMem/issues
10
+ Keywords: mcp,obsidian,memory,claude-code,codex,deepseek,agent,rag
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: Microsoft :: Windows
16
+ Classifier: Operating System :: MacOS
17
+ Classifier: Operating System :: POSIX :: Linux
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Software Development
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Requires-Dist: numpy>=1.24
26
+ Requires-Dist: jsonschema>=4
27
+ Requires-Dist: pyyaml>=6
28
+ Requires-Dist: watchdog>=3
29
+ Requires-Dist: requests>=2.28
30
+ Requires-Dist: zstandard>=0.21
31
+ Requires-Dist: onnxruntime>=1.17
32
+ Requires-Dist: tokenizers>=0.19
33
+ Provides-Extra: torch
34
+ Requires-Dist: torch>=2.1; extra == "torch"
35
+ Requires-Dist: transformers>=4.40; extra == "torch"
36
+ Provides-Extra: test
37
+ Requires-Dist: pytest>=7; extra == "test"
38
+ Dynamic: license-file
39
+
40
+ <div align="center">
41
+
42
+ <img src="assets/icon.png" width="96" alt="OriMem icon">
43
+
44
+ # OriMem
45
+
46
+ **Long-term memory for coding agents, kept in your own Obsidian vault.**
47
+
48
+ One local MCP server and one skill, shared by Claude Code, Codex and DeepSeek Harness —
49
+ recall project context across sessions, write confirmed results back with receipts, and capture every conversation automatically.
50
+
51
+ [![CI](https://github.com/Wen5555/OriMem/actions/workflows/ci.yml/badge.svg)](https://github.com/Wen5555/OriMem/actions/workflows/ci.yml)
52
+ ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
53
+ ![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
54
+ ![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
55
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
56
+
57
+ **English** · [简体中文](README.zh-CN.md)
58
+
59
+ </div>
60
+
61
+ <!-- mcp-name: io.github.Wen5555/orimem -->
62
+
63
+ ---
64
+
65
+ ## Why OriMem
66
+
67
+ Coding agents forget everything when a session ends, and each agent keeps its history in its own private format. OriMem gives them **one shared, human-readable memory**:
68
+
69
+ - 🗂️ **Your vault is the memory.** Plain Markdown in an Obsidian vault you can read, edit and back up. The index is just a cache.
70
+ - 🔎 **Hybrid recall.** Multilingual E5 embeddings + SQLite FTS5 + wiki-links. Short snippets first, exact evidence on demand, so context stays small.
71
+ - ✅ **Verified write-back.** `prepare_record → diff → commit_record` with hash checks, backups, read-back and receipts. It never silently overwrites a note you edited.
72
+ - 🎙️ **Automatic capture.** Hooks save each Claude Code / Codex / dsh session as a transcript note when a turn ends. Tool output, reasoning, injected system context, sub-agents and automations are left out.
73
+ - 📅 **Daily summary (opt-in).** The agent asks you once; if you agree, a scheduled job writes the day's journal through the same verified writer.
74
+ - 🔒 **Local only.** No cloud calls, no telemetry. The embedding model is pinned and checksum-verified, and runs on CPU through ONNX Runtime (no PyTorch needed).
75
+
76
+ ## Quick start
77
+
78
+ **Windows (PowerShell)**
79
+
80
+ ```powershell
81
+ irm https://raw.githubusercontent.com/Wen5555/OriMem/main/scripts/install.ps1 | iex
82
+ ```
83
+
84
+ **macOS / Linux**
85
+
86
+ ```bash
87
+ curl -LsSf https://raw.githubusercontent.com/Wen5555/OriMem/main/scripts/install.sh | sh
88
+ ```
89
+
90
+ The installer sets up [uv](https://github.com/astral-sh/uv) if needed, installs OriMem into an isolated environment (about 120 MB, Python provided by uv), then runs `orimem init`. `init` asks three questions — vault path, conversation capture (default on), daily summary (default "ask me later") — downloads the 470 MB embedding model, and connects every agent it finds. Restart your agents afterwards.
91
+
92
+ Then just talk to your agent:
93
+
94
+ > *"What did we decide about the export feature last week?"*
95
+ > *"Record that the WebGPU renderer is done and the next step is drag-to-reorder layers."*
96
+
97
+ <details>
98
+ <summary>Other ways to install</summary>
99
+
100
+ ```bash
101
+ uv tool install orimem-mcp
102
+ ```
103
+
104
+ ```bash
105
+ pipx install orimem-mcp
106
+ ```
107
+
108
+ The PyPI distribution is `orimem-mcp`; the command it installs is `orimem`. To run the MCP server without installing it first, use `uvx --from orimem-mcp orimem mcp`.
109
+
110
+ ```bash
111
+ orimem init
112
+ ```
113
+
114
+ Non-interactive: `orimem init --yes --vault ~/Notes --agents claude,codex`. Behind a slow network, the installer switches to mirrors automatically when PyPI is unreachable (`ORIMEM_MIRROR=cn` forces it).
115
+ </details>
116
+
117
+ ## Supported agents
118
+
119
+ | Agent | MCP server | Skill | Hooks (capture on turn end) | Transcripts read from |
120
+ |---|---|---|---|---|
121
+ | **Claude Code** | `claude mcp add -s user orimem` | `~/.claude/skills/orimem` | `~/.claude/settings.json` | `~/.claude/projects/*/<uuid>.jsonl` |
122
+ | **Codex** | `[mcp_servers.orimem]` in `~/.codex/config.toml` | `~/.codex/skills/orimem` | `~/.codex/hooks.json` | `~/.codex/sessions/**/rollout-*.jsonl` |
123
+ | **DeepSeek Harness (dsh)** | `dsh-mcp-client` entry in the profile's `cordis.patch.yml` | `~/.dsh/skills/orimem` | `dsh-hooks-claude-code` bridge | `~/.dsh/sessions/**/session.v4.jsonl.zstd` |
124
+ | Any other MCP client | `orimem snippet` prints the JSON | copy the skill folder | — | — |
125
+
126
+ **Claude Code users** can also install it as a plugin (MCP server, skill and hooks in one step; still needs the `orimem` command):
127
+
128
+ ```text
129
+ /plugin install orimem --marketplace Wen5555/OriMem
130
+ ```
131
+
132
+ On older Claude Code versions: `/plugin marketplace add Wen5555/OriMem`, then `/plugin install orimem@orimem`.
133
+
134
+ **DeepSeek Harness users** can also add the [`dsh-orimem`](integrations/dsh) bundle from the community plugin market (or `dsh plugin --profile <name> add dsh-orimem-<version>.tgz` from a [release](https://github.com/Wen5555/OriMem/releases)); it needs the `orimem` command from the quick start.
135
+
136
+ `orimem install` and `orimem uninstall` only add or remove OriMem's own entries, and every edited file is backed up first. Marker blocks in TOML/YAML files are removed byte for byte; JSON files keep all other content.
137
+
138
+ ## How it works
139
+
140
+ ```mermaid
141
+ flowchart LR
142
+ subgraph Agents
143
+ CC[Claude Code]
144
+ CX[Codex]
145
+ DS[DeepSeek Harness]
146
+ end
147
+ CC & CX & DS -- "MCP (stdio)" --> M[orimem mcp]
148
+ CC & CX & DS -. "Stop hook" .-> H[orimem hook]
149
+ M --> S[(local service<br/>loopback only)]
150
+ H -- "capture this session" --> S
151
+ S --> I[(SQLite: chunks · E5 vectors<br/>FTS5 · links · ledger)]
152
+ S <--> V[/"Obsidian vault<br/>(Markdown = source of truth)"/]
153
+ S -- "every 2 min" --> T[agent transcripts]
154
+ ```
155
+
156
+ - **Recall:** `task_context` binds the current project; `recall` returns ranked snippets; `evidence` fetches exact source text with offsets and hashes.
157
+ - **Write-back:** the agent proposes a complete note change; OriMem checks the expected hash, backs up, writes, re-reads, verifies the claimed text and issues a receipt.
158
+ - **Capture:** per-agent parsers mirror ordinary user/assistant turns into one pipeline, which stages them and projects stable transcript notes under `90 归档/Codex佐证/`. Hooks hand the work to the running service (falling back to a detached capture process), so they also work inside sandboxed hook runners such as dsh's.
159
+
160
+ ## Configuration
161
+
162
+ Settings live in `~/.orimem/config.toml`. Change them with `orimem config set <key> <value>` or ask your agent, which uses the `config_set` tool.
163
+
164
+ | Key | Default | Meaning |
165
+ |---|---|---|
166
+ | `vault` | `~/.orimem/vault` | Obsidian vault path |
167
+ | `capture.enabled` | `true` | Capture conversations into the vault |
168
+ | `capture.sources` | `["claude","codex","dsh"]` | Which agents to capture |
169
+ | `capture.since` | install time | Older sessions are not back-filled (`orimem capture --backfill` does it on request) |
170
+ | `capture.exclude_cwd` | `[]` | Never capture sessions started in these folders |
171
+ | `daily_summary.enabled` | `"ask"` | `"ask"` = ask once, off until answered · `true` · `false` |
172
+ | `daily_summary.time` | `"22:30"` | When the daily job runs |
173
+ | `daily_summary.agent` | auto | `claude` or `codex` runs the summary |
174
+ | `recall.hf_endpoint` | auto | Model download endpoint (falls back to hf-mirror.com) |
175
+
176
+ ## Reference
177
+
178
+ <details>
179
+ <summary><b>CLI</b></summary>
180
+
181
+ | Command | What it does |
182
+ |---|---|
183
+ | `orimem init [-y]` | First-time setup |
184
+ | `orimem install / uninstall [--agent claude,codex,dsh] [--dsh-profile NAME]` | Connect or disconnect agents |
185
+ | `orimem doctor` | Check config, model, embedder, dependencies and agents |
186
+ | `orimem capture [--source X] [--session ID] [--backfill]` | Capture now |
187
+ | `orimem sync` · `orimem recall "query" --scope "10 项目"` | Index / search from the shell |
188
+ | `orimem daily status / run [--dry-run] / apply` | Daily summary |
189
+ | `orimem model status / download [--torch] / import DIR` | Embedding model |
190
+ | `orimem config get / set / path` | Settings |
191
+ | `orimem snippet` | MCP JSON + AGENTS.md snippet for other clients |
192
+ | `orimem --home DIR …` | Use another data directory (written into generated agent commands) |
193
+ </details>
194
+
195
+ <details>
196
+ <summary><b>MCP tools</b></summary>
197
+
198
+ | Tool | Purpose |
199
+ |---|---|
200
+ | `task_context` | Bind the current folder/task to a project entry |
201
+ | `recall` | Hybrid search (snippets) |
202
+ | `evidence` | Exact source text for result ids |
203
+ | `list_sessions` · `get_session_messages` | Browse captured conversations |
204
+ | `prepare_record` · `commit_record` | Verified write-back |
205
+ | `initialize` | Create a project/course entry |
206
+ | `lifecycle` | Source reading, candidates, corrections |
207
+ | `health` · `sync` · `archive_history` | Maintenance |
208
+ | `config_get` · `config_set` · `capture_now` | Settings and capture |
209
+ </details>
210
+
211
+ <details>
212
+ <summary><b>Vault layout</b></summary>
213
+
214
+ ```text
215
+ 00 收件箱/ inbox and knowledge candidates
216
+ 10 项目/ one page per project (status, next action)
217
+ 15 课程/ courses
218
+ 30 知识/ reusable knowledge
219
+ 50 日记/ 每日/ (daily) · 每周/ (weekly)
220
+ 90 归档/ archive; 90 归档/Codex佐证/ holds captured transcripts
221
+ 95 AI 工作区/ agent work notes
222
+ ```
223
+
224
+ Writes are limited to `layout.folders`. `.obsidian` and files outside the vault are never read or modified.
225
+ </details>
226
+
227
+ ## FAQ
228
+
229
+ **Do I need a GPU or PyTorch?** No. Embeddings run on CPU through ONNX Runtime. `orimem[torch]` plus `orimem model download --torch` enables the optional PyTorch backend, which produces identical vectors.
230
+
231
+ **Can I use my existing vault?** Yes. Point `vault` at it. OriMem only adds the folders it needs and never rewrites existing notes outside the verified write-back flow.
232
+
233
+ **I'm in mainland China.** Both installers detect an unreachable PyPI and switch to the Tsinghua PyPI mirror, the npmmirror Python builds and hf-mirror.com.
234
+
235
+ **How do I turn capture off for a project?** `orimem config set capture.exclude_cwd '["D:/work/secret"]'`. To turn it off everywhere: `orimem config set capture.enabled false`.
236
+
237
+ **How do I remove everything?** `orimem uninstall`, then `uv tool uninstall orimem-mcp`. Your vault and `~/.orimem` stay until you delete them.
238
+
239
+ ## Roadmap
240
+
241
+ - [ ] Configurable / English vault layout
242
+ - [ ] More agents (Cursor, Gemini CLI, OpenCode)
243
+ - [ ] Optional quantized ONNX model for low-memory machines
244
+
245
+ ## Contributing
246
+
247
+ ```bash
248
+ git clone https://github.com/Wen5555/OriMem && cd OriMem
249
+ ```
250
+
251
+ ```bash
252
+ uv venv && uv pip install -e ".[test]"
253
+ ```
254
+
255
+ ```bash
256
+ uv run pytest
257
+ ```
258
+
259
+ A manual end-to-end checklist for each agent is in [docs/TESTING.md](docs/TESTING.md). Issues and pull requests are welcome.
260
+
261
+ ## License
262
+
263
+ [MIT](LICENSE)
@@ -0,0 +1,224 @@
1
+ <div align="center">
2
+
3
+ <img src="assets/icon.png" width="96" alt="OriMem icon">
4
+
5
+ # OriMem
6
+
7
+ **Long-term memory for coding agents, kept in your own Obsidian vault.**
8
+
9
+ One local MCP server and one skill, shared by Claude Code, Codex and DeepSeek Harness —
10
+ recall project context across sessions, write confirmed results back with receipts, and capture every conversation automatically.
11
+
12
+ [![CI](https://github.com/Wen5555/OriMem/actions/workflows/ci.yml/badge.svg)](https://github.com/Wen5555/OriMem/actions/workflows/ci.yml)
13
+ ![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
14
+ ![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
15
+ ![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
16
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
17
+
18
+ **English** · [简体中文](README.zh-CN.md)
19
+
20
+ </div>
21
+
22
+ <!-- mcp-name: io.github.Wen5555/orimem -->
23
+
24
+ ---
25
+
26
+ ## Why OriMem
27
+
28
+ Coding agents forget everything when a session ends, and each agent keeps its history in its own private format. OriMem gives them **one shared, human-readable memory**:
29
+
30
+ - 🗂️ **Your vault is the memory.** Plain Markdown in an Obsidian vault you can read, edit and back up. The index is just a cache.
31
+ - 🔎 **Hybrid recall.** Multilingual E5 embeddings + SQLite FTS5 + wiki-links. Short snippets first, exact evidence on demand, so context stays small.
32
+ - ✅ **Verified write-back.** `prepare_record → diff → commit_record` with hash checks, backups, read-back and receipts. It never silently overwrites a note you edited.
33
+ - 🎙️ **Automatic capture.** Hooks save each Claude Code / Codex / dsh session as a transcript note when a turn ends. Tool output, reasoning, injected system context, sub-agents and automations are left out.
34
+ - 📅 **Daily summary (opt-in).** The agent asks you once; if you agree, a scheduled job writes the day's journal through the same verified writer.
35
+ - 🔒 **Local only.** No cloud calls, no telemetry. The embedding model is pinned and checksum-verified, and runs on CPU through ONNX Runtime (no PyTorch needed).
36
+
37
+ ## Quick start
38
+
39
+ **Windows (PowerShell)**
40
+
41
+ ```powershell
42
+ irm https://raw.githubusercontent.com/Wen5555/OriMem/main/scripts/install.ps1 | iex
43
+ ```
44
+
45
+ **macOS / Linux**
46
+
47
+ ```bash
48
+ curl -LsSf https://raw.githubusercontent.com/Wen5555/OriMem/main/scripts/install.sh | sh
49
+ ```
50
+
51
+ The installer sets up [uv](https://github.com/astral-sh/uv) if needed, installs OriMem into an isolated environment (about 120 MB, Python provided by uv), then runs `orimem init`. `init` asks three questions — vault path, conversation capture (default on), daily summary (default "ask me later") — downloads the 470 MB embedding model, and connects every agent it finds. Restart your agents afterwards.
52
+
53
+ Then just talk to your agent:
54
+
55
+ > *"What did we decide about the export feature last week?"*
56
+ > *"Record that the WebGPU renderer is done and the next step is drag-to-reorder layers."*
57
+
58
+ <details>
59
+ <summary>Other ways to install</summary>
60
+
61
+ ```bash
62
+ uv tool install orimem-mcp
63
+ ```
64
+
65
+ ```bash
66
+ pipx install orimem-mcp
67
+ ```
68
+
69
+ The PyPI distribution is `orimem-mcp`; the command it installs is `orimem`. To run the MCP server without installing it first, use `uvx --from orimem-mcp orimem mcp`.
70
+
71
+ ```bash
72
+ orimem init
73
+ ```
74
+
75
+ Non-interactive: `orimem init --yes --vault ~/Notes --agents claude,codex`. Behind a slow network, the installer switches to mirrors automatically when PyPI is unreachable (`ORIMEM_MIRROR=cn` forces it).
76
+ </details>
77
+
78
+ ## Supported agents
79
+
80
+ | Agent | MCP server | Skill | Hooks (capture on turn end) | Transcripts read from |
81
+ |---|---|---|---|---|
82
+ | **Claude Code** | `claude mcp add -s user orimem` | `~/.claude/skills/orimem` | `~/.claude/settings.json` | `~/.claude/projects/*/<uuid>.jsonl` |
83
+ | **Codex** | `[mcp_servers.orimem]` in `~/.codex/config.toml` | `~/.codex/skills/orimem` | `~/.codex/hooks.json` | `~/.codex/sessions/**/rollout-*.jsonl` |
84
+ | **DeepSeek Harness (dsh)** | `dsh-mcp-client` entry in the profile's `cordis.patch.yml` | `~/.dsh/skills/orimem` | `dsh-hooks-claude-code` bridge | `~/.dsh/sessions/**/session.v4.jsonl.zstd` |
85
+ | Any other MCP client | `orimem snippet` prints the JSON | copy the skill folder | — | — |
86
+
87
+ **Claude Code users** can also install it as a plugin (MCP server, skill and hooks in one step; still needs the `orimem` command):
88
+
89
+ ```text
90
+ /plugin install orimem --marketplace Wen5555/OriMem
91
+ ```
92
+
93
+ On older Claude Code versions: `/plugin marketplace add Wen5555/OriMem`, then `/plugin install orimem@orimem`.
94
+
95
+ **DeepSeek Harness users** can also add the [`dsh-orimem`](integrations/dsh) bundle from the community plugin market (or `dsh plugin --profile <name> add dsh-orimem-<version>.tgz` from a [release](https://github.com/Wen5555/OriMem/releases)); it needs the `orimem` command from the quick start.
96
+
97
+ `orimem install` and `orimem uninstall` only add or remove OriMem's own entries, and every edited file is backed up first. Marker blocks in TOML/YAML files are removed byte for byte; JSON files keep all other content.
98
+
99
+ ## How it works
100
+
101
+ ```mermaid
102
+ flowchart LR
103
+ subgraph Agents
104
+ CC[Claude Code]
105
+ CX[Codex]
106
+ DS[DeepSeek Harness]
107
+ end
108
+ CC & CX & DS -- "MCP (stdio)" --> M[orimem mcp]
109
+ CC & CX & DS -. "Stop hook" .-> H[orimem hook]
110
+ M --> S[(local service<br/>loopback only)]
111
+ H -- "capture this session" --> S
112
+ S --> I[(SQLite: chunks · E5 vectors<br/>FTS5 · links · ledger)]
113
+ S <--> V[/"Obsidian vault<br/>(Markdown = source of truth)"/]
114
+ S -- "every 2 min" --> T[agent transcripts]
115
+ ```
116
+
117
+ - **Recall:** `task_context` binds the current project; `recall` returns ranked snippets; `evidence` fetches exact source text with offsets and hashes.
118
+ - **Write-back:** the agent proposes a complete note change; OriMem checks the expected hash, backs up, writes, re-reads, verifies the claimed text and issues a receipt.
119
+ - **Capture:** per-agent parsers mirror ordinary user/assistant turns into one pipeline, which stages them and projects stable transcript notes under `90 归档/Codex佐证/`. Hooks hand the work to the running service (falling back to a detached capture process), so they also work inside sandboxed hook runners such as dsh's.
120
+
121
+ ## Configuration
122
+
123
+ Settings live in `~/.orimem/config.toml`. Change them with `orimem config set <key> <value>` or ask your agent, which uses the `config_set` tool.
124
+
125
+ | Key | Default | Meaning |
126
+ |---|---|---|
127
+ | `vault` | `~/.orimem/vault` | Obsidian vault path |
128
+ | `capture.enabled` | `true` | Capture conversations into the vault |
129
+ | `capture.sources` | `["claude","codex","dsh"]` | Which agents to capture |
130
+ | `capture.since` | install time | Older sessions are not back-filled (`orimem capture --backfill` does it on request) |
131
+ | `capture.exclude_cwd` | `[]` | Never capture sessions started in these folders |
132
+ | `daily_summary.enabled` | `"ask"` | `"ask"` = ask once, off until answered · `true` · `false` |
133
+ | `daily_summary.time` | `"22:30"` | When the daily job runs |
134
+ | `daily_summary.agent` | auto | `claude` or `codex` runs the summary |
135
+ | `recall.hf_endpoint` | auto | Model download endpoint (falls back to hf-mirror.com) |
136
+
137
+ ## Reference
138
+
139
+ <details>
140
+ <summary><b>CLI</b></summary>
141
+
142
+ | Command | What it does |
143
+ |---|---|
144
+ | `orimem init [-y]` | First-time setup |
145
+ | `orimem install / uninstall [--agent claude,codex,dsh] [--dsh-profile NAME]` | Connect or disconnect agents |
146
+ | `orimem doctor` | Check config, model, embedder, dependencies and agents |
147
+ | `orimem capture [--source X] [--session ID] [--backfill]` | Capture now |
148
+ | `orimem sync` · `orimem recall "query" --scope "10 项目"` | Index / search from the shell |
149
+ | `orimem daily status / run [--dry-run] / apply` | Daily summary |
150
+ | `orimem model status / download [--torch] / import DIR` | Embedding model |
151
+ | `orimem config get / set / path` | Settings |
152
+ | `orimem snippet` | MCP JSON + AGENTS.md snippet for other clients |
153
+ | `orimem --home DIR …` | Use another data directory (written into generated agent commands) |
154
+ </details>
155
+
156
+ <details>
157
+ <summary><b>MCP tools</b></summary>
158
+
159
+ | Tool | Purpose |
160
+ |---|---|
161
+ | `task_context` | Bind the current folder/task to a project entry |
162
+ | `recall` | Hybrid search (snippets) |
163
+ | `evidence` | Exact source text for result ids |
164
+ | `list_sessions` · `get_session_messages` | Browse captured conversations |
165
+ | `prepare_record` · `commit_record` | Verified write-back |
166
+ | `initialize` | Create a project/course entry |
167
+ | `lifecycle` | Source reading, candidates, corrections |
168
+ | `health` · `sync` · `archive_history` | Maintenance |
169
+ | `config_get` · `config_set` · `capture_now` | Settings and capture |
170
+ </details>
171
+
172
+ <details>
173
+ <summary><b>Vault layout</b></summary>
174
+
175
+ ```text
176
+ 00 收件箱/ inbox and knowledge candidates
177
+ 10 项目/ one page per project (status, next action)
178
+ 15 课程/ courses
179
+ 30 知识/ reusable knowledge
180
+ 50 日记/ 每日/ (daily) · 每周/ (weekly)
181
+ 90 归档/ archive; 90 归档/Codex佐证/ holds captured transcripts
182
+ 95 AI 工作区/ agent work notes
183
+ ```
184
+
185
+ Writes are limited to `layout.folders`. `.obsidian` and files outside the vault are never read or modified.
186
+ </details>
187
+
188
+ ## FAQ
189
+
190
+ **Do I need a GPU or PyTorch?** No. Embeddings run on CPU through ONNX Runtime. `orimem[torch]` plus `orimem model download --torch` enables the optional PyTorch backend, which produces identical vectors.
191
+
192
+ **Can I use my existing vault?** Yes. Point `vault` at it. OriMem only adds the folders it needs and never rewrites existing notes outside the verified write-back flow.
193
+
194
+ **I'm in mainland China.** Both installers detect an unreachable PyPI and switch to the Tsinghua PyPI mirror, the npmmirror Python builds and hf-mirror.com.
195
+
196
+ **How do I turn capture off for a project?** `orimem config set capture.exclude_cwd '["D:/work/secret"]'`. To turn it off everywhere: `orimem config set capture.enabled false`.
197
+
198
+ **How do I remove everything?** `orimem uninstall`, then `uv tool uninstall orimem-mcp`. Your vault and `~/.orimem` stay until you delete them.
199
+
200
+ ## Roadmap
201
+
202
+ - [ ] Configurable / English vault layout
203
+ - [ ] More agents (Cursor, Gemini CLI, OpenCode)
204
+ - [ ] Optional quantized ONNX model for low-memory machines
205
+
206
+ ## Contributing
207
+
208
+ ```bash
209
+ git clone https://github.com/Wen5555/OriMem && cd OriMem
210
+ ```
211
+
212
+ ```bash
213
+ uv venv && uv pip install -e ".[test]"
214
+ ```
215
+
216
+ ```bash
217
+ uv run pytest
218
+ ```
219
+
220
+ A manual end-to-end checklist for each agent is in [docs/TESTING.md](docs/TESTING.md). Issues and pull requests are welcome.
221
+
222
+ ## License
223
+
224
+ [MIT](LICENSE)
@@ -0,0 +1,57 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "orimem-mcp"
7
+ version = "0.1.1"
8
+ description = "Local Obsidian-vault memory for coding agents (Claude Code, Codex, DeepSeek Harness) over MCP: hybrid recall, verified write-back, conversation capture and daily summaries."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "Orion" }]
13
+ keywords = ["mcp", "obsidian", "memory", "claude-code", "codex", "deepseek", "agent", "rag"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Environment :: Console",
17
+ "Intended Audience :: Developers",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Operating System :: Microsoft :: Windows",
20
+ "Operating System :: MacOS",
21
+ "Operating System :: POSIX :: Linux",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Topic :: Software Development",
26
+ ]
27
+ dependencies = [
28
+ "numpy>=1.24",
29
+ "jsonschema>=4",
30
+ "pyyaml>=6",
31
+ "watchdog>=3",
32
+ "requests>=2.28",
33
+ "zstandard>=0.21",
34
+ "onnxruntime>=1.17",
35
+ "tokenizers>=0.19",
36
+ ]
37
+
38
+ [project.optional-dependencies]
39
+ torch = ["torch>=2.1", "transformers>=4.40"]
40
+ test = ["pytest>=7"]
41
+
42
+ [project.scripts]
43
+ orimem = "orimem.cli:main"
44
+
45
+ [project.urls]
46
+ Homepage = "https://github.com/Wen5555/OriMem"
47
+ Documentation = "https://github.com/Wen5555/OriMem#readme"
48
+ Issues = "https://github.com/Wen5555/OriMem/issues"
49
+
50
+ [tool.setuptools.packages.find]
51
+ where = ["src"]
52
+
53
+ [tool.setuptools.package-data]
54
+ orimem = ["skill/**/*", "templates/**/*"]
55
+
56
+ [tool.pytest.ini_options]
57
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ __version__ = "0.1.1"
@@ -0,0 +1,4 @@
1
+ from orimem.cli import main
2
+
3
+ if __name__ == "__main__":
4
+ main()