{
  "markdown": "# Memory Mason\n\n![Memory Mason](img/cover.png)\n\n**Capture AI conversations. Build an Obsidian knowledge base. One command.**\n\n[![Stars](https://img.shields.io/github/stars/s-gryt/memory-mason?style=flat&color=e8734a)](https://github.com/s-gryt/memory-mason/stargazers)\n[![CI](https://github.com/s-gryt/memory-mason/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/s-gryt/memory-mason/actions/workflows/ci.yml)\n[![cov](https://raw.githubusercontent.com/s-gryt/memory-mason/gh-pages/badges/coverage.svg)](https://github.com/s-gryt/memory-mason/actions/workflows/ci.yml)\n[![Checked with Biome](https://img.shields.io/badge/Checked_with-Biome-60a5fa?style=flat&logo=biome)](https://biomejs.dev)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-8B5CF6)](https://code.claude.com/docs/en/discover-plugins)\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-Sergii%20Grytsaienko-0077B5?logo=linkedin)](https://www.linkedin.com/in/sergii-grytsaienko/)\n\n---\n\n## What It Does\n\nMemory Mason hooks into your AI coding agent and silently captures every conversation into daily Obsidian logs. When you're ready, run `/mmc` to compile raw logs into structured knowledge articles — concepts, synthesis pages, and MOCs — all interlinked with `[[wikilinks]]`. Then use `/mmq` to retrieve answers from your compiled knowledge base without leaving the conversation.\n\nNo API key needed. No cloud sync. Everything stays local in your Obsidian vault.\n\n### How data flows in\n\n```text\n[AI Conversation] ──> [Hook Runtime] ──> [Smart Filter] ──> [Obsidian Vault]\n   (any agent)          (automatic)       (6-stage pipe)      _raw/YYYY-MM-DD/\n```\n\nHooks capture prompts, tool results, and session transcripts into daily log files. Before anything reaches your vault, a six-stage filtering pipeline strips noise and protects sensitive data:\n\n1. **Tag stripping** — Removes system-reminder, system-instruction, and other injected tags\n2. **ANSI removal** — Strips terminal control characters from tool output\n3. **Event classification** — Categorizes each event as error, test result, discovery, exploration, meta, or noise. Exploration and meta events are discarded; errors and test results are always kept.\n4. **Prose compression** — Removes filler words and hedging phrases while preserving code blocks, URLs, inline code, and quoted strings\n5. **Sensitive content blocking** — Skips capture when input contains credentials, private keys, `.env` contents, or paths like `.ssh/` and `.aws/`\n6. **Deduplication** — Content-hash check prevents the same data from being written twice within a session\n\nMemory Mason's own commands (`/mmc`, `/mmq`, `/mml`, `/mms`, `/mma`, `/mmsetup`) and namespaced `/memory-mason:*` forms are automatically excluded from capture.\n\nRaw captures are stored in session-scoped files: `_raw/YYYY-MM-DD/{HHMMSS}-{sid8}-{NNN}.md` (session start time, 8-char session id prefix, 3-digit chunk index). Each file is capped at 512 KB; a 2 MB hard cap may force a split, marked with a `[!continued]` callout. One session's prompt→answer exchange never splits across files at the soft cap. Concurrent sessions never interleave. This keeps Obsidian responsive and ensures each file stays within LLM processing limits. No data is lost — every conversation turn is preserved, and Obsidian indexes all chunks for full-text search. The raw tier is append-only by design and is never auto-deleted; archive manually if desired. Token economics (raw vs. stored token counts and savings percentage) are tracked on every capture and reported by `/mms`, whether or not `minimize` is enabled — sanitize-only changes (e.g. tag stripping) still count. Enabling `minimize` adds prose compression on top, increasing savings further. See [docs/README.md](docs/README.md) for technical details on chunked storage.\n\n### How knowledge is built\n\n```text\n_raw/YYYY-MM-DD/ ──> /mmc compile ──> concepts/\n                                       sessions/         (per-session summaries)\n                                       atlas/            (MOCs + Bases views)\n                                       synthesis/\n                                       index.md\n```\n\nRun `/mmc` to compile daily logs into structured articles. The host LLM reads your raw logs and produces atomic concept pages, MOC navigation pages in `atlas/`, cross-session synthesis pages, and per-session summary notes in `sessions/` — all linked with `[[wikilinks]]` for Obsidian graph navigation. `atlas/bases/` holds Obsidian Bases views (sessions-timeline, decisions, contradictions, seedlings) for timeline queries; Bases requires Obsidian 1.9+.\n\n### How knowledge is retrieved\n\n```text\n/mmq \"How does auth work?\" ──> _meta/context.md ──> concepts/ + atlas/ + synthesis/ ──> answer with [[citations]]\n```\n\nRun `/mmq` with a question. Memory Mason checks session context for recent focus first, then searches compiled articles (including a grep stage for exact matches) and the `sessions/` tier for temporal questions, synthesizes an answer, and cites sources with `[[wikilinks]]` back to the original concepts. `/mmq insights` surfaces candidate-skill recommendations from coaching advisories. Your knowledge base grows with every session and becomes more useful over time.\n\n## Commands\n\n| Command | What it does |\n|:--------|:-------------|\n| `/mmc` | Compile raw captures into concepts, MOCs, synthesis pages, and per-session summaries in `sessions/`; update session context and source manifest; maintain Bases views in `atlas/bases/` |\n| `/mmq` | Answer questions from your knowledge base with source citations; grep stage + sessions tier for temporal queries; `/mmq insights` for coaching-advisory skill recommendations |\n| `/mml` | Run knowledge base health checks (broken links, stale content, manifest integrity, and more) |\n| `/mms` | Show knowledge base status, health summary, and compilation coverage; token-savings metrics tracked on every capture, larger when `minimize` is enabled |\n| `/mma` | Archive old build log entries to keep the knowledge base log compact |\n| `/mmsetup` | First-time vault configuration (or uninstall) |\n\n## Install\n\nPick your agent. Restart the host after install.\n\n> **Prerequisite:** [Node.js](https://nodejs.org) must be installed.\n\n### Plugin install (recommended)\n\n| Agent | Install command |\n|:------|:----------------|\n| **Claude Code** | `/plugin marketplace add s-gryt/memory-mason` then `/plugin install memory-mason@s-gryt` |\n| **GitHub Copilot CLI** | `copilot plugin marketplace add s-gryt/memory-mason` then `copilot plugin install memory-mason@s-gryt` |\n| **VS Code Copilot** | Command Palette → `Chat: Install Plugin From Source` → `https://github.com/s-gryt/memory-mason` |\n| **Codex** | `codex plugin marketplace add s-gryt/memory-mason` then open `/plugins`, search `Memory Mason`, install |\n| **Gemini CLI** | `gemini extensions install https://github.com/s-gryt/memory-mason` |\n| **Cursor / Windsurf / Cline** | `npx skills add s-gryt/memory-mason -a <agent> -s '*' -y` |\n\nAfter install, run `/mmsetup` to configure your Obsidian vault path.\n\n### Shell install (direct)\n\nFor any platform, you can also install directly with a shell command:\n\n```bash\n# macOS / Linux\nbash <(curl -fsSL https://raw.githubusercontent.com/s-gryt/memory-mason/main/install.sh) --agent <name>\n\n# Windows PowerShell\n& ([scriptblock]::Create((iwr https://raw.githubusercontent.com/s-gryt/memory-mason/main/install.ps1 -UseBasicParsing).Content)) -Agent <name>\n```\n\nReplace `<name>` with `claude`, `copilot`, `codex`, or `all`.\n\nSee [docs/README.md](docs/README.md) for marketplace installs, workspace-level installs, and advanced configuration.\n\n## Configuration\n\nRun `/mmsetup` to configure your vault path interactively, or create a config file manually.\nConfig can be set globally (`~/.memory-mason/`) or per-project (project root). When multiple\nsources exist, vault path resolves in priority order: project `.env` → project `memory-mason.json`\n→ global `.env` → `~/.memory-mason/config.json`. Per-session `MEMORY_MASON_SYNC`,\n`MEMORY_MASON_CAPTURE_MODE`, and `MEMORY_MASON_MINIMIZE` environment variables override file config\n(process env takes highest precedence). `MEMORY_MASON_SUBFOLDER` is layered independently from the\nsame file priority order, so a nearer project subfolder still wins even if a different source\nprovided the vault path. See [docs/README.md](docs/README.md) for details.\n\n**Project isolation:** Give each project its own `.env` or `memory-mason.json` with a dedicated\n`MEMORY_MASON_SUBFOLDER` value. Projects without per-project config fall back to global config and\nshare a single capture stream — projects wanting data isolation must define per-project config.\n\n**Skills-only hosts (Cursor, Windsurf, Cline, Gemini CLI):** `npx skills add` installs the six\nknowledge base commands but provides no capture hooks. Hooks require plugin or shell install on a\nsupported hook-capable agent (Claude Code, Copilot, Codex).\n\n### .env format\n\n`MEMORY_MASON_VAULT_PATH` sets the Obsidian vault location. `MEMORY_MASON_SUBFOLDER` sets the\ndirectory inside the vault. `MEMORY_MASON_SYNC` is optional — capture is enabled by default; set\nit to `false` to pause capture. `MEMORY_MASON_CAPTURE_MODE` is optional and controls what gets\ncaptured:\n\n- **`lite`** (default) — User prompts, errors, test results, and final assistant reply per stop event. Minimal vault footprint.\n- **`full`** — Everything in lite, plus all filtered tool events, plan outputs, agent findings, mid-run discoveries, and pre-compact transcripts. Exploration reads, meta tools, and noise are still filtered out.\n\n`MEMORY_MASON_MINIMIZE` is optional — set to `true` to enable deterministic lossless\ncompression (whitespace and punctuation normalization) on assistant narrative text before writing to the vault. Content is compacted but never dropped; code blocks, user prompts,\nURLs, quoted strings, and errors are never modified. Default is `false` (raw text stored verbatim).\nToken-savings metrics are reported by `/mms` on every capture regardless of this setting; enabling it increases savings further.\n\nProcess environment variables override file config for a single session and take highest precedence.\n\n```env\nMEMORY_MASON_VAULT_PATH=/path/to/your/obsidian/vault\nMEMORY_MASON_SUBFOLDER=ai-knowledge\nMEMORY_MASON_SYNC=true\nMEMORY_MASON_CAPTURE_MODE=lite\nMEMORY_MASON_MINIMIZE=false\n```\n\n### JSON format\n\n`vaultPath` sets the Obsidian vault location. `subfolder` sets the directory inside the vault. `sync` is optional — capture is enabled by default; set it to `false` to pause capture. `captureMode` is optional — `lite` (default) captures user prompts, errors, test results, and final assistant replies; `full` adds all filtered tool events and pre-compact transcripts. `minimize` is optional — when `true`, a deterministic compression algorithm reduces assistant narrative text before vault writes (default `false`). Use this format for `memory-mason.json` in a project root or `~/.memory-mason/config.json` for global config (`/mmsetup` creates the global file automatically).\n\n```json\n{\n  \"vaultPath\": \"/path/to/your/obsidian/vault\",\n  \"subfolder\": \"ai-knowledge\",\n  \"sync\": true,\n  \"captureMode\": \"lite\",\n  \"minimize\": false\n}\n```\n\n## Uninstall\n\nRun `/mmsetup` and say \"uninstall\" for guided removal. Your vault content is never deleted.\n\nFor skills-only installs: `npx skills remove s-gryt/memory-mason -a <agent>`\n\n## Troubleshooting\n\n**Hooks fail silently by design.** They never block the agent or surface errors in the chat. If capture seems inactive:\n\n1. **Verify capture is working.** Check `{vault}/{subfolder}/_raw/` for a folder named today's date (e.g., `2026-07-05`). Inside it you should see files named `{HHMMSS}-{sid8}-{NNN}.md`. Also inspect `{vault}/{subfolder}/_meta/state.json` — the `capture_metrics` field records the number of items written this session.\n\n2. **Check config resolution.** The hook resolves config in this order: project `.env` → project `memory-mason.json` → `~/.memory-mason/.env` → `~/.memory-mason/config.json`. If none of these exist, the hook throws an explicit error and logs it; no vault writes occur. Run `/mmsetup` to create the global config.\n\n3. **Disable capture for a session.** Set `MEMORY_MASON_SYNC=false` as a process environment variable (or in your project `.env`) to pause capture without uninstalling.\n\n4. **Hook file locations per platform:**\n   - Claude Code: `~/.claude/hooks/memory-mason/`\n   - GitHub Copilot: `~/.copilot/hooks/memory-mason/`\n   - Codex: `~/.codex/hooks/memory-mason/`\n\n5. **Skills-only hosts.** Cursor, Windsurf, Cline, and Gemini CLI receive the six knowledge base commands but have no hook runtime installed. No capture occurs on these platforms regardless of config.\n\n## Packaging\n\n| Surface | Path |\n|:--------|:-----|\n| Claude Code plugin | [.claude-plugin](.claude-plugin) |\n| GitHub Copilot plugin | [.github/plugin](.github/plugin) |\n| Copilot plugin hooks | [hooks.json](hooks.json) |\n| Codex plugin | [plugins/memory-mason](plugins/memory-mason) |\n| Gemini CLI extension | [gemini-extension.json](gemini-extension.json) + [GEMINI.md](GEMINI.md) |\n| Agent Skills source | [skills](skills) |\n| Hook runtime | [hooks](hooks) |\n| CI | [.github/workflows/ci.yml](.github/workflows/ci.yml) |\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\n## Star History\n\n<a href=\"https://www.star-history.com/?repos=s-gryt%2Fmemory-mason&type=date&legend=top-left\">\n <picture>\n   <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=s-gryt/memory-mason&type=date&theme=dark&legend=top-left\" />\n   <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=s-gryt/memory-mason&type=date&legend=top-left\" />\n   <img alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=s-gryt/memory-mason&type=date&legend=top-left\" />\n </picture>\n</a>\n",
  "bytes": 13980,
  "sha": "269e729a8ec14a12bf8a5e4f6a491bd9f3fadb08cd1895c0ac67899758e33ed0",
  "repo_slug": "s-gryt/memory-mason",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_s_gryt_memory_mason_b63c3399/readme"
}