Skip to content
Back to search

memctl

Local Markdown memory for AI agents: a single-binary Go MCP server with full-text search, a link graph and git-backed history.

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 20 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/agonzaNET/memctl with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/agonzaNET/memctl'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agonzanet--memctl/badge.svg)](/listings/agonzanet--memctl)

HTML

<a href="/listings/agonzanet--memctl"><img src="/api/listings/agonzanet--memctl/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.

Download the archive for your machine from the [releases](https://github.com/agonzaNET/memctl/releases): `memctl_<version>_linux_amd64.tar.gz`, `memctl_<version>_linux_arm64.tar.gz` or `memctl_<version>_darwin_arm64.tar.gz` (Apple silicon), and `SHA256SUMS`.

sha256sum -c --ignore-missing SHA256SUMS      # macOS: shasum -a 256 -c --ignore-missing SHA256SUMS
tar -xzf memctl_<version>_<os>_<arch>.tar.gz
install -m 0755 memctl ~/.local/bin/          # or any folder on your PATH
memctl version

On macOS, a binary downloaded with a browser carries a quarantine attribute, and Gatekeeper refuses to start it because it is not signed. Remove the attribute once: `xattr -d com.apple.quarantine ~/.local/bin/memctl`.

Windows is not supported.

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.

README.md · README · 164 lines
  1. # memctl
  2. Local Markdown memory for AI agents: a single-binary Go MCP server with
  3. full-text search, a link graph and git-backed history.
  4. Your notes stay plain Markdown files in one folder. `memctl` serves them to an
  5. MCP client such as Claude Code or Claude Desktop, so an agent can search,
  6. read, write, edit, move and delete notes, and follow the links between them.
  7. Every change a tool makes is a git commit in the notes folder. Nothing leaves
  8. your machine: there is no server, no account and no network access.
  9. **Status:** pre-1.0 (`0.x`). The tools and the note format may still change
  10. between minor versions; see [`CHANGELOG.md`](CHANGELOG.md).
  11. ## Install
  12. Download the archive for your machine from the
  13. [releases](https://github.com/agonzaNET/memctl/releases):
  14. `memctl_<version>_linux_amd64.tar.gz`, `memctl_<version>_linux_arm64.tar.gz`
  15. or `memctl_<version>_darwin_arm64.tar.gz` (Apple silicon), and `SHA256SUMS`.
  16. ```sh
  17. sha256sum -c --ignore-missing SHA256SUMS # macOS: shasum -a 256 -c --ignore-missing SHA256SUMS
  18. tar -xzf memctl_<version>_<os>_<arch>.tar.gz
  19. install -m 0755 memctl ~/.local/bin/ # or any folder on your PATH
  20. memctl version
  21. ```
  22. On macOS, a binary downloaded with a browser carries a quarantine attribute,
  23. and Gatekeeper refuses to start it because it is not signed. Remove the
  24. attribute once: `xattr -d com.apple.quarantine ~/.local/bin/memctl`.
  25. Windows is not supported.
  26. ## Use it from an MCP client
  27. `memctl mcp` is started by the client as a child process and talks MCP over
  28. stdin and stdout. Point `--root` at your notes folder; it should be a git
  29. repository (`git init` it once) so that every change is recorded.
  30. Claude Code:
  31. ```sh
  32. claude mcp add --scope user memory -- memctl mcp --root ~/notes
  33. ```
  34. Claude Desktop (`claude_desktop_config.json`; use absolute paths, `~` is not
  35. expanded there):
  36. ```json
  37. {
  38. "mcpServers": {
  39. "memory": {
  40. "command": "/Users/you/.local/bin/memctl",
  41. "args": ["mcp", "--root", "/Users/you/notes"]
  42. }
  43. }
  44. }
  45. ```
  46. Only one `memctl mcp` can serve a notes folder at a time. A second client
  47. configured on the same folder fails to start with
  48. `root <path> is in use by memctl (pid N)`; give each client its own folder.
  49. ### Flags
  50. | Flag | Environment variable | Default | Meaning |
  51. |---|---|---|---|
  52. | `--root DIR` | `MEMCTL_ROOT` | (required) | The notes folder |
  53. | `--log-level LEVEL` | `MEMCTL_LOG_LEVEL` | `info` | `debug`, `info`, `warn` or `error`; JSON logs on stderr |
  54. | `--git-author "Name <email>"` | `MEMCTL_GIT_AUTHOR` | `memctl <memctl@localhost>` | Author and committer of the tool commits |
  55. A flag wins over its environment variable.
  56. ### Tools
  57. | Tool | What it does |
  58. |---|---|
  59. | `search` | Full-text search (BM25), with type, tag and folder filters |
  60. | `note_read` | A note, or one section of it, with its links and its `sha256` |
  61. | `context` | The notes linked to and from a note, up to three hops |
  62. | `list` | Notes by folder, type or tag |
  63. | `note_write` | Create a note from a title and a body |
  64. | `note_edit` | Append, replace a section, or replace one piece of text; needs the `sha256` from `note_read`, so a change made meanwhile in an editor is never overwritten |
  65. | `note_move` | Move or rename a note; the old path and title go into `aliases`, so links keep working |
  66. | `note_delete` | Delete a note; git history keeps it |
  67. ## Notes
  68. A note is a Markdown file with optional YAML frontmatter:
  69. ```markdown
  70. ---
  71. title: PAN-OS upgrade procedure
  72. type: runbook
  73. tags: [palo-alto, firewall]
  74. aliases: [PAN-OS upgrade]
  75. created: 2026-11-19T10:12:00+01:00
  76. updated: 2026-11-19T10:12:00+01:00
  77. ---
  78. # PAN-OS upgrade procedure
  79. Free text. A link such as [[hosts/PA-850]] is indexed as links_to.
  80. ## Observations
  81. - [risk] HA pair must be upgraded passive first
  82. ## Relations
  83. - applies_to [[hosts/PA-850]]
  84. ```
  85. - Link to a note by its path without `.md` (recommended, always unique), by
  86. its title, or by one of its aliases.
  87. - Observations (`- [category] text`) and relations (`- type [[Target]]`) are
  88. read only under the `## Observations` and `## Relations` headings.
  89. - Files and folders whose names start with `.`, and what your `.gitignore`
  90. files exclude, are not notes. `memctl` keeps its own files in `.memory/`,
  91. which git ignores.
  92. - Edit notes in any editor at any time; the next tool call sees the change.
  93. The full format is in the [design](docs/design/solution-design.md#note-format-v1).
  94. ## Git
  95. Each tool write is committed in the background, a few seconds after the last
  96. write of a burst, as `memory: <tool> <title>` or `memory: <n> changes`. Only
  97. the files a tool changed are committed: your own staged or unstaged changes
  98. are left alone. Pending changes are committed before `memctl mcp` exits.
  99. `memctl` never pushes, pulls or changes branches. A notes folder outside git
  100. works too, without commits.
  101. ## Check a notes folder
  102. ```sh
  103. memctl check --root ~/notes
  104. ```
  105. Reports frontmatter and structure problems, unsupported Markdown, dangling,
  106. ambiguous and stale links, skipped files and a missing git repository. It
  107. exits 1 when there are errors. It reads only, and can run while `memctl mcp`
  108. serves the same folder.
  109. ## Building from source
  110. ```sh
  111. mise install # the pinned Go toolchain
  112. make build # bin/memctl for this machine
  113. make verify # tests, vet, gofmt, the docs checks and the script tests
  114. make dist VERSION=0.1.0 # the release archives in dist/
  115. ```
  116. See [`docs/agents/environment.md`](docs/agents/environment.md).
  117. ## Design and decisions
  118. - [`docs/design/`](docs/design/) — the product design (the source of truth).
  119. - [`docs/adr/`](docs/adr/) — architecture decision records (the why).
  120. - [`docs/specs/`](docs/specs/) — capability specs (the what).
  121. - [`CHANGELOG.md`](CHANGELOG.md) — notable changes per release.
  122. ## License
  123. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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