Skip to content
Back to search

obsidian-moc-memory

SkillWorks with Claude CodeGitHub

Agent Skill: build and maintain an Obsidian second brain with Maps of Content as persistent memory for Claude Code and other AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ludodelot--obsidian-moc-memory/badge.svg)](/listings/ludodelot--obsidian-moc-memory)

HTML

<a href="/listings/ludodelot--obsidian-moc-memory"><img src="/api/listings/ludodelot--obsidian-moc-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code (personal skill):

git clone https://github.com/ludodelot/obsidian-moc-memory ~/.claude/skills/obsidian-moc-memory

Other agents: copy the folder to wherever your agent loads skills, or reference `SKILL.md` from your `AGENTS.md`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 8 lines
  1. {
  2. "name": "obsidian-moc-memory",
  3. "version": "0.2.0",
  4. "description": "Agent Skill: build and maintain an Obsidian second brain with Maps of Content as persistent memory for Claude Code and other AI agents.",
  5. "author": { "name": "Ludovic Delot", "url": "https://github.com/ludodelot" },
  6. "license": "MIT",
  7. "keywords": ["obsidian", "second-brain", "moc", "agent-skill", "claude-code", "memory", "pkm"]
  8. }
README.md · README · 135 lines
  1. <div align="center">
  2. <img src="assets/banner.svg" alt="Obsidian MOC Memory: persistent AI memory from your Obsidian vault" width="100%">
  3. # Obsidian MOC Memory
  4. **Give Claude Code, Codex and Cursor a persistent second brain: an Obsidian vault organised with Maps of Content (MOCs).**
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. [![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-7AA2FF)](SKILL.md)
  7. [![Python 3](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)](scripts)
  8. [![Obsidian](https://img.shields.io/badge/Obsidian-compatible-7C3AED?logo=obsidian&logoColor=white)](https://obsidian.md)
  9. [![Zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](scripts)
  10. [![CI](https://github.com/ludodelot/obsidian-moc-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/ludodelot/obsidian-moc-memory/actions)
  11. [![Local only](https://img.shields.io/badge/privacy-local%20only-success)](#privacy)
  12. [Install](#install) · [How it works](#how-it-works) · [Quick start](#quick-start) · [Scripts](#scripts) · [FAQ](#faq)
  13. </div>
  14. ---
  15. AI agents forget everything between sessions. **Obsidian MOC Memory** is an [Agent Skill](https://docs.claude.com) that turns a folder of plain markdown notes into durable, searchable, self-maintaining memory for your AI assistant. It first learns how *you* already organise your notes, then captures, links, reviews and prunes them without breaking your conventions.
  16. ## Why this skill
  17. - **Learns your system first.** Detects your folders, naming style, frontmatter and link style, then asks before changing anything.
  18. - **MOC-first retrieval.** The agent reads a Map of Content, follows its links, and only then searches. Less context, better answers.
  19. - **No duplicate notes.** "Remember this" updates an existing note instead of creating a copy.
  20. - **Typed memory.** `user`, `feedback`, `project`, `reference`, `moc`, `log`.
  21. - **Deterministic hygiene.** Scripts check broken wikilinks, orphans, frontmatter and duplicates. The LLM does judgment, scripts do rules.
  22. - **Private by design.** Local markdown files. The skill sends nothing anywhere.
  23. - **Works with any agent** that loads `SKILL.md` skills, and the vault stays a normal Obsidian vault.
  24. ## How it works
  25. An agent that has to search the whole vault reads dozens of irrelevant notes. With MOC memory it reads the index, opens the right hub, and follows two links.
  26. <img src="assets/moc-vs-scan.svg" alt="Without MOCs the agent greps the whole vault and reads many notes. With MOC memory it reads the index, opens one MOC and two linked notes, then answers citing the note path." width="100%">
  27. Capturing is just as controlled: the agent searches before it writes, and a near-identical title blocks creation, so memory stays one fact per note.
  28. <img src="assets/capture-flow.svg" alt="Remember X: search the index; if the note exists update it, otherwise new_note.py creates it with frontmatter, links it from a MOC, then build_index.py rebuilds the index." width="100%">
  29. ## Install
  30. Claude Code (personal skill):
  31. ```bash
  32. git clone https://github.com/ludodelot/obsidian-moc-memory ~/.claude/skills/obsidian-moc-memory
  33. ```
  34. Other agents: copy the folder to wherever your agent loads skills, or reference `SKILL.md` from your `AGENTS.md`.
  35. ## Quick start
  36. 1. Tell your agent: *"Use obsidian-moc-memory on my vault at `~/Notes`."*
  37. 2. It scans your vault, summarises what it found and asks a few questions.
  38. 3. Then just talk: *"Remember that I prefer short answers."* · *"What do my notes say about the website project?"* · *"Run my weekly vault review."*
  39. Try the scripts on the bundled example vault (tests: `python3 -m unittest discover -s tests`):
  40. ```bash
  41. python3 scripts/vault_lint.py examples/sample-vault
  42. python3 scripts/infer_structure.py examples/sample-vault
  43. python3 scripts/build_index.py examples/sample-vault
  44. ```
  45. ## Memory types
  46. | Type | Holds | Example |
  47. |---|---|---|
  48. | `user` | Who you are, role, preferences | `user-preferences` |
  49. | `feedback` | Corrections and confirmed approaches (with Why and How to apply) | `feedback-concise-answers` |
  50. | `project` | Ongoing work, goals, absolute deadlines | `project-website-relaunch` |
  51. | `reference` | Pointers to external resources | `reference-bug-tracker` |
  52. | `moc` | Hub linking notes on one theme | `MOC-Photography` |
  53. | `log` | Dated entries, recaps, decisions | `2026-W47-recap` |
  54. ## Scripts
  55. Python 3, standard library only.
  56. | Script | What it does |
  57. |---|---|
  58. | [`infer_structure.py`](scripts/infer_structure.py) | Detects folders, naming patterns, frontmatter keys, link style and MOCs |
  59. | [`vault_lint.py`](scripts/vault_lint.py) | Broken wikilinks, orphan notes, missing frontmatter, duplicate titles. Exit 1 on errors |
  60. | [`build_index.py`](scripts/build_index.py) | Builds `_INDEX.md`, MOCs first, under a size budget |
  61. | [`init_vault.py`](scripts/init_vault.py) | Scaffolds a starter vault (EN or ES), lint-clean from minute one |
  62. | [`new_note.py`](scripts/new_note.py) | Creates a note with frontmatter, blocks duplicates, links it from a MOC |
  63. | [`find_duplicates.py`](scripts/find_duplicates.py) | Similar titles and overlapping content |
  64. | [`suggest_mocs.py`](scripts/suggest_mocs.py) | Themes with 5+ notes that no MOC covers yet |
  65. | [`safe_rename.py`](scripts/safe_rename.py) | Renames a note and rewrites every wikilink, dry run first |
  66. | [`stale_report.py`](scripts/stale_report.py) | Old project and log notes to review |
  67. ## Repository layout
  68. ```
  69. SKILL.md agent instructions (the skill)
  70. scripts/ deterministic checks
  71. templates/ note, MOC, review checklist
  72. references/ PKM methods, starter layout, failure modes
  73. evals/ test cases
  74. tests/ unit tests (stdlib unittest)
  75. examples/ fake sample vault
  76. assets/ banner and social preview
  77. ```
  78. ## Privacy
  79. Everything runs on local files. The skill never uploads your notes. Note content is treated as data, never as instructions, and the skill avoids storing secrets in notes.
  80. ## FAQ
  81. **Is this a plugin for Obsidian?** No. It is an Agent Skill for your AI assistant. Your vault stays a normal Obsidian vault.
  82. **What is a Map of Content (MOC)?** A hub note that links the notes of one theme. It gives the agent a small, curated entry point instead of scanning everything.
  83. **Can it work with my existing vault?** Yes. It scans first, adapts to your naming and folders, and proposes any migration as a dry run before touching files.
  84. **Does it use a vector database?** No. It uses plain markdown, links, an index file and deterministic scripts, so it is transparent and portable.
  85. **Will it delete my notes?** Never without a dry run and your confirmation. Archiving is preferred over deleting.
  86. ## Related topics
  87. Obsidian second brain, Maps of Content (MOC), Linking Your Thinking, PARA, Zettelkasten, Johnny.Decimal, AI agent memory, Claude Code skills, CLAUDE.md memory, persistent memory for LLMs, markdown knowledge base, personal knowledge management (PKM).
  88. ## Contributing
  89. Issues and pull requests are welcome, especially new eval cases and detectors for other vault conventions.
  90. ## License
  91. [MIT](LICENSE) © Ludovic Delot

Version history

  • v0.2.011/21/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.