Skip to main content
OriMem icon

OriMem

Long-term memory for coding agents, kept in your own Obsidian vault.

One local MCP server and one skill, shared by Claude Code, Codex and DeepSeek Harness — recall project context across sessions, write confirmed results back with receipts, and capture every conversation automatically.

CI Python MCP Platforms License: MIT

English · 简体中文


Why OriMem

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:

  • 🗂️ Your vault is the memory. Plain Markdown in an Obsidian vault you can read, edit and back up. The index is just a cache.
  • 🔎 Hybrid recall. Multilingual E5 embeddings + SQLite FTS5 + wiki-links. Short snippets first, exact evidence on demand, so context stays small.
  • ✅ Verified write-back. prepare_record → diff → commit_record with hash checks, backups, read-back and receipts. It never silently overwrites a note you edited.
  • 🎙️ 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.
  • 📅 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.
  • 🔒 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).

Quick start

Windows (PowerShell)

irm https://raw.githubusercontent.com/Wen5555/OriMem/main/scripts/install.ps1 | iex

macOS / Linux

curl -LsSf https://raw.githubusercontent.com/Wen5555/OriMem/main/scripts/install.sh | sh

The installer sets up 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.

Then just talk to your agent:

"What did we decide about the export feature last week?" "Record that the WebGPU renderer is done and the next step is drag-to-reorder layers."

Other ways to install
uv tool install orimem-mcp
pipx install orimem-mcp

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.

orimem init

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).

Supported agents

Agent MCP server Skill Hooks (capture on turn end) Transcripts read from
Claude Code claude mcp add -s user orimem ~/.claude/skills/orimem ~/.claude/settings.json ~/.claude/projects/*/<uuid>.jsonl
Codex [mcp_servers.orimem] in ~/.codex/config.toml ~/.codex/skills/orimem ~/.codex/hooks.json ~/.codex/sessions/**/rollout-*.jsonl
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
Any other MCP client orimem snippet prints the JSON copy the skill folder — —

Claude Code users can also install it as a plugin (MCP server, skill and hooks in one step; still needs the orimem command):

/plugin install orimem --marketplace Wen5555/OriMem

On older Claude Code versions: /plugin marketplace add Wen5555/OriMem, then /plugin install orimem@orimem.

DeepSeek Harness users can also add the dsh-orimem bundle from the community plugin market (or dsh plugin --profile <name> add dsh-orimem-<version>.tgz from a release); it needs the orimem command from the quick start.

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.

How it works

flowchart LR
    subgraph Agents
        CC[Claude Code]
        CX[Codex]
        DS[DeepSeek Harness]
    end
    CC & CX & DS -- "MCP (stdio)" --> M[orimem mcp]
    CC & CX & DS -. "Stop hook" .-> H[orimem hook]
    M --> S[(local service<br/>loopback only)]
    H -- "capture this session" --> S
    S --> I[(SQLite: chunks · E5 vectors<br/>FTS5 · links · ledger)]
    S <--> V[/"Obsidian vault<br/>(Markdown = source of truth)"/]
    S -- "every 2 min" --> T[agent transcripts]
  • Recall: task_context binds the current project; recall returns ranked snippets; evidence fetches exact source text with offsets and hashes.
  • 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.
  • 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.

Configuration

Settings live in ~/.orimem/config.toml. Change them with orimem config set <key> <value> or ask your agent, which uses the config_set tool.

Key Default Meaning
vault ~/.orimem/vault Obsidian vault path
capture.enabled true Capture conversations into the vault
capture.sources ["claude","codex","dsh"] Which agents to capture
capture.since install time Older sessions are not back-filled (orimem capture --backfill does it on request)
capture.exclude_cwd [] Never capture sessions started in these folders
daily_summary.enabled "ask" "ask" = ask once, off until answered · true · false
daily_summary.time "22:30" When the daily job runs
daily_summary.agent auto claude or codex runs the summary
recall.hf_endpoint auto Model download endpoint (falls back to hf-mirror.com)

Reference

CLI
Command What it does
orimem init [-y] First-time setup
orimem install / uninstall [--agent claude,codex,dsh] [--dsh-profile NAME] Connect or disconnect agents
orimem doctor Check config, model, embedder, dependencies and agents
orimem capture [--source X] [--session ID] [--backfill] Capture now
orimem sync · orimem recall "query" --scope "10 项目" Index / search from the shell
orimem daily status / run [--dry-run] / apply Daily summary
orimem model status / download [--torch] / import DIR Embedding model
orimem config get / set / path Settings
orimem snippet MCP JSON + AGENTS.md snippet for other clients
orimem --home DIR … Use another data directory (written into generated agent commands)
MCP tools
Tool Purpose
task_context Bind the current folder/task to a project entry
recall Hybrid search (snippets)
evidence Exact source text for result ids
list_sessions · get_session_messages Browse captured conversations
prepare_record · commit_record Verified write-back
initialize Create a project/course entry
lifecycle Source reading, candidates, corrections
health · sync · archive_history Maintenance
config_get · config_set · capture_now Settings and capture
Vault layout
00 收件箱/   inbox and knowledge candidates
10 项目/     one page per project (status, next action)
15 课程/     courses
30 知识/     reusable knowledge
50 日记/     每日/ (daily) · 每周/ (weekly)
90 归档/     archive; 90 归档/Codex佐证/ holds captured transcripts
95 AI 工作区/ agent work notes

Writes are limited to layout.folders. .obsidian and files outside the vault are never read or modified.

FAQ

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.

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.

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.

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.

How do I remove everything? orimem uninstall, then uv tool uninstall orimem-mcp. Your vault and ~/.orimem stay until you delete them.

Roadmap

  • Configurable / English vault layout
  • More agents (Cursor, Gemini CLI, OpenCode)
  • Optional quantized ONNX model for low-memory machines

Contributing

git clone https://github.com/Wen5555/OriMem && cd OriMem
uv venv && uv pip install -e ".[test]"
uv run pytest

A manual end-to-end checklist for each agent is in docs/TESTING.md. Issues and pull requests are welcome.

License

MIT

Metadata

Release files for orimem-mcp 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for orimem-mcp 0.1.1
File Size Uploaded Provenance Actions
orimem_mcp-0.1.1.tar.gz 179.7 kB With provenance Details for orimem_mcp-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for orimem-mcp 0.1.1
File Interpreter ABI Platform Actions
orimem_mcp-0.1.1-py3-none-any.whl Python 3 none any Details for orimem_mcp-0.1.1-py3-none-any.whl

Total release size: 380.7 kB

Release files / orimem_mcp-0.1.1.tar.gz

Download URL orimem_mcp-0.1.1.tar.gz
Size 179.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a00e86abcc8d29b0a56adc9721a4a51bc7a738dd744b90e138ca5dd53ef9429f
BLAKE2b-256 checksum
How to use checksums
6b399fb5628148fd6bbf029d007f1a2697661275ffc13be55c1f657e2acb1e77
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / orimem_mcp-0.1.1-py3-none-any.whl

Download URL orimem_mcp-0.1.1-py3-none-any.whl
Size 201.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
00af013c2ea5aab22fcc38f189e5fe1f90a43dfa15e57d9e8f3d0ded8da955cb
BLAKE2b-256 checksum
How to use checksums
ffa0ecbc54ce9bfe741a3c45b5d6b8a403c31e95a0bc52a47ca55fcd504d3915
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for orimem-mcp 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for orimem_mcp-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page