Skip to content
Back to search

basicmachines-co

MarketplaceWorks with Claude CodeGitHubIncomplete

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 11 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/basicmachines-co/basic-memory 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/basicmachines-co/basic-memory'

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/basicmachines-co-basic-memory/badge.svg)](/listings/basicmachines-co-basic-memory)

HTML

<a href="/listings/basicmachines-co-basic-memory"><img src="/api/listings/basicmachines-co-basic-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

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/marketplace.json · Manifest · 29 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "basicmachines-co",
  3. "owner": {
  4. "name": "Basic Machines",
  5. "email": "hello@basicmachines.co"
  6. },
  7. "metadata": {
  8. "description": "Official Basic Memory plugins from the canonical basic-memory repository",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "basic-memory",
  14. "source": "./plugins/claude-code",
  15. "description": "The bridge between Claude's working memory and Basic Memory's durable knowledge graph \u2014 session briefings, pre-compaction checkpoints, and capture reflexes",
  16. "version": "1.0.0",
  17. "author": {
  18. "name": "Basic Machines"
  19. },
  20. "keywords": [
  21. "memory",
  22. "knowledge",
  23. "mcp",
  24. "specs",
  25. "context"
  26. ]
  27. }
  28. ]
  29. }
README.md · README · 703 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- mcp-name: io.github.basicmachines-co/basic-memory -->
  2. [![MCP Toplist](https://mcptoplist.com/badge/io.github.basicmachines-co%2Fbasic-memory.svg)](https://mcptoplist.com/server/io.github.basicmachines-co%2Fbasic-memory)
  3. [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
  4. [![PyPI version](https://badge.fury.io/py/basic-memory.svg)](https://badge.fury.io/py/basic-memory)
  5. [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
  6. [![Tests](https://github.com/basicmachines-co/basic-memory/workflows/Tests/badge.svg)](https://github.com/basicmachines-co/basic-memory/actions)
  7. [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
  8. ![](https://badge.mcpx.dev?type=server 'MCP Server')
  9. ![](https://badge.mcpx.dev?type=dev 'MCP Dev')
  10. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/basicmachines-co/basic-memory)
  11. ## Skip the install — try Basic Memory in the cloud
  12. Claude, Codex, or Cursor connected in 30 seconds. No Python, no JSON, no
  13. terminal. **$15.00/mo locked in for life** (12.50/mo yearly pricing). 7-day free
  14. trial — cancel any time before day 7 if it's not for you. Beta pricing —
  15. sign up now and your rate never goes up. OSS users: code `BMFOSS` takes
  16. another 20% off for 3 months.
  17. [Start free trial →](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme&utm_content=banner)
  18. ### Basic Memory Teams is now available!
  19. Give your team a single, shared cloud workspace. Knowledge isn't confined to one person — anything a teammate writes is immediately available to everyone else and to their AI assistants.
  20. Edit a note together in real time, hand work off between humans and agents, and build one connected knowledge base instead of scattered copies. Same pricing - start with one user and add more as needed.
  21. ---
  22. # Basic Memory
  23. ### Your AI never forgets again.
  24. Pick up right where you left off — in Claude, Codex, Cursor, ChatGPT, or
  25. anything that speaks [MCP](https://modelcontextprotocol.io). Your knowledge
  26. lives as Markdown files that both you and your AI can read, write, and
  27. search.
  28. - **Local-first.** Plain text on your disk. Forever.
  29. - **Two-way.** AI and humans write to the same files; sync keeps them in step.
  30. - **A real knowledge graph.** Observations and wikilinks compound into context.
  31. - **Semantic search.** Find notes by meaning, not just keywords, with optional
  32. cross-encoder reranking for higher-quality vector and hybrid results.
  33. - **MCP-native.** Works with every major AI client and IDE.
  34. - **Progressive tool discovery.** Every tool is tagged with behavior hints
  35. (read-only, destructive, idempotent) so agents pick the right tool on
  36. demand — no wasted context trying things to see what they do.
  37. - **Cloud, optional.** Sync across devices when you want — never required.
  38. ## Get started
  39. Pick the path that fits you. Both run the same product on the same Markdown.
  40. <table>
  41. <tr>
  42. <th width="50%">☁️ &nbsp; Cloud</th>
  43. <th width="50%">💻 &nbsp; Local install</th>
  44. </tr>
  45. <tr>
  46. <td valign="top">
  47. **30 seconds.** Sign up, connect your AI client, done.
  48. - Works in any browser
  49. - Mobile, web, desktop
  50. - Cross-device sync built in
  51. - We handle hosting, backups, snapshots
  52. **$15.00/mo locked for life** · 7-day free trial · cancel any time
  53. [**Start free trial →**](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme&utm_content=quickstart)
  54. </td>
  55. <td valign="top">
  56. **2 minutes.** Install, configure your AI client, run.
  57. - Free forever (AGPL-3.0)
  58. - All data on your disk
  59. - Air-gapped friendly
  60. - Requires Python via [`uv`](https://docs.astral.sh/uv/)
  61. ```bash
  62. uv tool install basic-memory --prerelease=allow
  63. ```
  64. `--prerelease=allow` is required: Basic Memory 0.23 depends on a FastMCP 4
  65. pre-release, and `uv` only accepts pre-releases of transitive dependencies when
  66. told to — without the flag it silently installs an older release. The same flag
  67. goes on every `uvx` / `uv tool upgrade` command below.
  68. For Postgres deployments that store semantic vectors in Milvus, install the
  69. first-party optional extra instead:
  70. ```bash
  71. uv tool install "basic-memory[milvus]" --prerelease=allow
  72. ```
  73. [**Configure your client ↓**](#connect-your-ai-client)
  74. </td>
  75. </tr>
  76. </table>
  77. ## What people are saying
  78. > Basic Memory changed my whole relationship with LLMs. I switched from GPT
  79. > and Gemini to exclusively Claude and Claude Code because of this
  80. > integration and am completely revamping all our company's processes around
  81. > a Basic Memory workflow.
  82. >
  83. > — **Alex**, TrainerDay
  84. > Basic Memory is the missing 'wow' factor in AI chatbots. Now I can't
  85. > imagine Claude or Claude Code without it.
  86. >
  87. > — **Caleb**, Caleb Picker Consulting
  88. > I don't code without Basic Memory anymore. It's such a time saver to be
  89. > able to refer to projects I don't currently have active and keep a running
  90. > log of all my learnings and ProTips.
  91. >
  92. > — **@groksrc**, Developer
  93. More on [basicmemory.com](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme).
  94. ## Basic Memory Cloud
  95. The hosted version of Basic Memory. Same product, same Markdown files, same
  96. MCP tools — we just host the database, run the sync, and put it on your
  97. phone.
  98. ### What you get
  99. - **Every device, same brain.** Your knowledge graph on web, mobile, and
  100. desktop. No copy-paste between machines.
  101. - **Connect any MCP client.** Claude Desktop, Claude Code, Codex, Cursor,
  102. ChatGPT (Custom GPTs), VS Code — one-click connect from the web app.
  103. - **Bidirectional sync to local.** Edit on your phone, see it in Obsidian on
  104. your laptop. rclone-powered with conflict resolution.
  105. - **Snapshots and backups.** Point-in-time restore. Browse history. Never
  106. lose a note.
  107. - **No lock-in.** Your notes are plain Markdown. Export to local Markdown any
  108. time — same files, same format, same wikilinks. Cancel anytime, your data
  109. stays yours.
  110. Built on WorkOS AuthKit, Neon Postgres, and Tigris S3.
  111. ### Pricing
  112. **$15.00/mo, locked in for the life of your subscription** (regular price
  113. $19). Sign up during beta and the rate never goes up — as long as you stay
  114. subscribed, you keep the price. One plan, no tiers, no surprise upgrades.
  115. Unlimited notes, unlimited projects, every feature.
  116. - 7-day free trial. Cancel any time before day 7 if it's not for you.
  117. - Cancel anytime after that too — export your notes whenever you want.
  118. - OSS users: code `BMFOSS` for another 20% off for 3 months (~$11.40/mo).
  119. [**Start your 7-day free trial →**](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme&utm_content=cloud-section)
  120. ## Cloud vs. local
  121. | | Cloud | Local |
  122. |---|---|---|
  123. | **Setup time** | 30 seconds | 2 minutes (requires Python) |
  124. | **Cost** | $15.00/mo, locked for life (7-day trial) | Free |
  125. | **Storage** | We host (Tigris S3) | Your disk |
  126. | **Cross-device sync** | Built in | Manual (Git, Syncthing, etc.) |
  127. | **Mobile access** | Yes (web + app) | No |
  128. | **Air-gapped** | No | Yes |
  129. | **Your data stays yours** | Yes — export anytime | Yes — already there |
  130. | **Source code** | AGPL-3.0 | AGPL-3.0 |
  131. | **Snapshots & backups** | Built in | Roll your own |
  132. Both paths use the same OSS engine and the same Markdown files. There's no
  133. lock-in either way — flip between them when your needs change.
  134. ## Works with the tools you already use
  135. | Client | Transport | Notes |
  136. |---|---|---|
  137. | Cloud web app | https | Sign in at basicmemory.com — no install |
  138. | [Claude Desktop](#claude-desktop) | stdio/https | macOS / Windows / Linux |
  139. | [Claude Code](#claude-code) | stdio/https | `claude mcp add` |
  140. | [Codex](#codex-cli) | stdio/https | OpenAI's coding agent |
  141. | [Cursor](#cursor) | stdio/https | `.cursor/mcp.json` |
  142. | [VS Code](#vs-code) | stdio/https | Native MCP support |
  143. | [ChatGPT](#chatgpt) | https | Custom GPT actions (`search` / `fetch`) |
  144. | [Obsidian](#obsidian) | — | Reads/writes the same Markdown directly |
  145. | Anything MCP | stdio/https | If it speaks MCP, it works |
  146. ## Official agent packages
  147. This repository is also the canonical home for Basic Memory's host-native
  148. agent packages. The core Python package, Claude Code plugin, shared skills,
  149. Hermes plugin, and OpenClaw plugin all ship from the same source tree.
  150. Maintainers can verify the whole consolidated surface from the repo root:
  151. ```bash
  152. just package-check
  153. ```
  154. Package-local justfiles are also available when working inside one host:
  155. ```bash
  156. just package-check-claude-code
  157. just package-check-skills
  158. just package-check-hermes
  159. just package-check-openclaw
  160. ```
  161. ### Claude Code plugin
  162. The Claude Code plugin is the bridge between Claude's working memory and Basic
  163. Memory — session-start briefings, pre-compaction checkpoints, an opt-in capture
  164. output style, and `/basic-memory:bm-setup` · `:remember` · `:share` · `:status`.
  165. **Connect the Basic Memory MCP server first** — see [Connect your AI
  166. client](#connect-your-ai-client). The plugin's hooks and skills call it, so it's a
  167. hard prerequisite. Then install the plugin:
  168. ```bash
  169. bm install claude-code
  170. ```
  171. That registers the marketplace and installs the plugin through Claude Code. Add
  172. `--scope project` to declare both in the repository's settings for a team, or
  173. `--dry-run` to see the underlying `claude plugin` commands without running them.
  174. Source: [`plugins/claude-code`](plugins/claude-code).
  175. ### Shared skills
  176. Framework-agnostic `SKILL.md` files live in [`skills/`](skills). If your
  177. Skills CLI supports repository subdirectory sources:
  178. ```bash
  179. npx skills add basicmachines-co/basic-memory/skills -g
  180. ```
  181. For Claude and ChatGPT, upload `basic-memory.zip` or `basic-memory-chatgpt.zip`
  182. from the [`skills-latest`](https://github.com/basicmachines-co/basic-memory/releases/tag/skills-latest)
  183. release; see [`skills/README.md`](skills/README.md#installation).
  184. If your installed Skills CLI cannot load that source, update the CLI or copy
  185. the `memory-*` directories from `skills/` into your agent's skills directory.
  186. ### Hermes
  187. Hermes keeps its native plugin shape under [`integrations/hermes`](integrations/hermes):
  188. ```bash
  189. hermes plugins install basicmachines-co/basic-memory/integrations/hermes
  190. ```
  191. Hermes does not install a plugin's Python dependencies, so also add the `mcp`
  192. package to the Hermes venv — see the [plugin README](integrations/hermes/README.md#install)
  193. for that step and the supported Hermes releases.
  194. ### OpenClaw
  195. OpenClaw stays package-native and publishes from
  196. [`integrations/openclaw`](integrations/openclaw):
  197. ```bash
  198. openclaw plugins install @basicmemory/openclaw-basic-memory
  199. ```
  200. ## Pick up where you left off
  201. https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc
  202. ## Connect your AI client
  203. If you went the [Cloud](#get-started) route, the web app walks you through
  204. client connect. The snippets below are for local installs.
  205. ### Claude Desktop
  206. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
  207. ```json
  208. {
  209. "mcpServers": {
  210. "basic-memory": {
  211. "command": "uvx",
  212. "args": ["--prerelease=allow", "basic-memory", "mcp"]
  213. }
  214. }
  215. }
  216. ```
  217. Restart Claude Desktop. Notes live in `~/basic-memory` by default.
  218. <details>
  219. <summary><b>Claude Code, Codex CLI, Cursor, VS Code, ChatGPT, Obsidian</b></summary>
  220. ### Claude Code
  221. ```bash
  222. claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp
  223. ```
  224. For the full memory bridge — session briefings, pre-compaction checkpoints, and
  225. the `/basic-memory:*` commands — also install the [Claude Code
  226. plugin](#claude-code-plugin) on top of this.
  227. ### Codex CLI
  228. Add to `~/.codex/config.toml`:
  229. ```toml
  230. [mcp_servers.basic-memory]
  231. command = "uvx"
  232. args = ["--prerelease=allow", "basic-memory", "mcp"]
  233. ```
  234. Codex can keep its default MCP approval behavior, or you can pre-approve eligible
  235. Basic Memory tools by adding this server-scoped setting to the same table:
  236. ```toml
  237. [mcp_servers.basic-memory]
  238. command = "uvx"
  239. args = ["--prerelease=allow", "basic-memory", "mcp"]
  240. default_tools_approval_mode = "approve"
  241. ```
  242. This does not disable Codex approvals globally or expand which Basic Memory
  243. projects the server can access. Codex still requires approval for tools that
  244. advertise a destructive annotation, including Basic Memory's writes, edits, and
  245. deletes. If you installed the Basic Memory Codex plugin, use its
  246. [plugin-scoped configuration](plugins/codex/README.md#mcp-approvals) instead.
  247. ### Cursor
  248. Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
  249. ```json
  250. {
  251. "mcpServers": {
  252. "basic-memory": {
  253. "command": "uvx",
  254. "args": ["--prerelease=allow", "basic-memory", "mcp"]
  255. }
  256. }
  257. }
  258. ```
  259. ### VS Code
  260. Add to your User Settings (JSON):
  261. ```json
  262. {
  263. "mcp": {
  264. "servers": {
  265. "basic-memory": {
  266. "command": "uvx",
  267. "args": ["--prerelease=allow", "basic-memory", "mcp"]
  268. }
  269. }
  270. }
  271. }
  272. ```
  273. ### ChatGPT
  274. Basic Memory exposes OpenAI-compatible `search` and `fetch` tools for Custom
  275. GPT actions. See the [ChatGPT integration
  276. guide](https://docs.basicmemory.com/integrations/chatgpt/?utm_source=github&utm_medium=referral&utm_campaign=readme).
  277. ### Obsidian
  278. No setup. Point Obsidian at `~/basic-memory` (or your project folder) and the
  279. same wikilinks, frontmatter, and Markdown your AI writes appear in your graph
  280. view. Edit either side — sync handles the rest.
  281. </details>
  282. Try a prompt:
  283. ```
  284. "Create a note about our project architecture decisions."
  285. "Find information about JWT auth in my notes."
  286. "What have I been working on this week?"
  287. ```
  288. ## What's New
  289. - **Automatic updates.** Basic Memory keeps itself up to date for `uv tool`
  290. and Homebrew installs; `bm update` triggers a manual check.
  291. - **Semantic vector search.** Find notes by meaning, not just keywords.
  292. Hybrid full-text + vector ranking with FastEmbed embeddings, on SQLite or
  293. Postgres.
  294. - **Optional search reranking.** Rescore the strongest vector and hybrid
  295. candidates with a local FastEmbed cross-encoder or a LiteLLM-backed provider.
  296. - **Schema system.** Infer, validate, and diff the structure of your
  297. knowledge base with `bm_schema_infer()`, `bm_schema_validate()`, and
  298. `bm_schema_diff()`.
  299. - **Per-project cloud routing.** Route individual projects through the cloud
  300. while others stay local, via API key (`bm project set-cloud`).
  301. - **Explicit note changes.** `bm_edit` updates existing notes; `bm_write`
  302. creates notes and guards against accidental overwrites.
  303. - **Richer search results.** Matched chunk text is included so the LLM gets
  304. context, not just hits.
  305. - **FastMCP 3.0 + tool annotations.** Every tool ships with MCP behavior
  306. hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
  307. `openWorldHint`) so agents can discover capabilities progressively at
  308. runtime instead of guessing or burning tokens.
  309. - **CLI overhaul.** `--json` output for scripting, workspace-aware commands,
  310. and an htop-inspired project dashboard.
  311. Full [CHANGELOG](CHANGELOG.md) for v0.18 → v0.20.
  312. ## Optional cross-encoder reranking
  313. Reranking adds a second relevance pass after vector or hybrid retrieval. It is
  314. disabled by default because it adds inference latency and, for the local
  315. provider, a first-run model download. Text, title, and permalink searches keep
  316. their existing ranking.
  317. Enable the default local FastEmbed reranker:
  318. ```bash
  319. export BASIC_MEMORY_RERANKER_ENABLED=true
  320. ```
  321. The default model is `jinaai/jina-reranker-v1-tiny-en`. To use a hosted
  322. reranker through LiteLLM instead, first [install the optional LiteLLM
  323. SDK](docs/litellm-provider.md#install-the-optional-sdk), then configure it:
  324. ```bash
  325. export BASIC_MEMORY_RERANKER_ENABLED=true
  326. export BASIC_MEMORY_RERANKER_PROVIDER=litellm
  327. export BASIC_MEMORY_RERANKER_MODEL=cohere/rerank-v3.5
  328. export COHERE_API_KEY=...
  329. ```
  330. The feature fails fast on invalid configuration and does not silently fall
  331. back to retrieval order when an enabled provider fails. See the
  332. [semantic search guide](docs/semantic-search.md#cross-encoder-reranking) for
  333. provider setup, all settings, tuning, pagination, and failure behavior.
  334. ## Why Basic Memory
  335. Most LLM conversations are ephemeral. You ask a question, get an answer, then
  336. everything is forgotten. Workarounds have limits:
  337. - **Chat history** captures conversations but isn't structured knowledge.
  338. - **RAG** lets the LLM query your documents but not write back to them.
  339. - **Vector DBs** need complex infra and usually live in someone else's cloud.
  340. - **Knowledge graphs** need specialized tooling to maintain.
  341. Basic Memory takes a simpler path: **structured Markdown files that humans
  342. and LLMs both read and write.**
  343. - All knowledge stays in plain files you control.
  344. - Both sides read and write to the same files.
  345. - Familiar Markdown with semantic patterns — no new format to learn.
  346. - A traversable graph the LLM can follow link by link.
  347. - Works with the editors you already use (Obsidian, VS Code, anything).
  348. - Just files plus a local SQLite index. No servers required.
  349. ## How it works
  350. You're chatting normally about coffee:
  351. > I've been experimenting with brewing methods. Pour over gives more clarity
  352. > than French press, water at 205°F seems best, and freshly ground beans
  353. > make a huge difference.
  354. Ask the LLM to capture it:
  355. > "Make a note on coffee brewing methods."
  356. A Markdown file appears in your project directory in real time:
  357. ```markdown
  358. ---
  359. title: Coffee Brewing Methods
  360. permalink: coffee-brewing-methods
  361. tags: [coffee, brewing]
  362. ---
  363. # Coffee Brewing Methods
  364. ## Observations
  365. - [method] Pour over highlights subtle flavors over body
  366. - [technique] Water at 205°F (96°C) extracts optimal compounds
  367. - [principle] Freshly ground beans preserve aromatics
  368. ## Relations
  369. - relates_to [[Coffee Bean Origins]]
  370. - requires [[Proper Grinding Technique]]
  371. - affects [[Flavor Extraction]]
  372. ```
  373. Next session, the LLM picks up the thread. It follows the relations to
  374. surface what you already know about Ethiopian beans and burr grinders, and
  375. builds on it instead of starting over. You see the same files in Obsidian or
  376. your editor. Edit them by hand — the AI sees your changes too.
  377. Real two-way flow: humans edit Markdown, LLMs read/write through MCP, sync
  378. keeps everything consistent, and the source of truth is always your files.
  379. ## The Markdown format
  380. Each file is an `Entity`. Entities have `Observations` (facts about them) and
  381. `Relations` (links to other entities). That's the whole grammar.
  382. ### Frontmatter
  383. ```markdown
  384. ---
  385. title: <Entity title>
  386. type: note
  387. permalink: <uri-slug>
  388. tags: [optional, list]
  389. ---
  390. ```
  391. ### Observations
  392. Facts about the entity. Categories in `[brackets]`, tags with `#`, optional
  393. context in parens.
  394. ```markdown
  395. - [method] Pour over highlights subtle flavors
  396. - [tip] Grind medium-fine for V60 #brewing
  397. - [fact] Lighter roasts contain more caffeine than dark
  398. - [resource] James Hoffmann's V60 technique on YouTube
  399. - [question] How does temperature affect compound extraction?
  400. ```
  401. ### Relations
  402. Wiki-style links that form the graph. Single-token relation types, or quote
  403. multi-word ones.
  404. ```markdown
  405. - pairs_well_with [[Chocolate Desserts]]
  406. - grown_in [[Ethiopia]]
  407. - requires [[Burr Grinder]]
  408. - "pairs well with" [[Dark Chocolate]]
  409. ```
  410. Bare `- [[Target]]` and prose `- Worth checking out [[Target]]` index as
  411. `links_to`. Full reference in the
  412. [docs](https://docs.basicmemory.com/concepts/knowledge-format?utm_source=github&utm_medium=referral&utm_campaign=readme).
  413. ## MCP tools
  414. Basic Memory exposes these tools to any MCP client. Every tool is annotated
  415. with MCP behavior hints (read-only, destructive, idempotent, open-world) so
  416. agents can pick the right one without trial-and-error:
  417. - **Content:** `bm_write`, `bm_read`, `bm_edit`, `bm_move`, `bm_delete`
  418. - **Search & discovery:** `bm_search`, `bm_list`, `bm_find`
  419. - **Knowledge graph:** `bm_context`
  420. - **Projects:** `bm_project_list`, `bm_project_create`, `bm_recent`;
  421. `bm_project_delete` is separate and requires server opt-in.
  422. - **Schema:** `bm_schema_validate`, `bm_schema_infer`, `bm_schema_diff`
  423. - **Manual:** `bm_man`
  424. - **Cloud connector adapters:** `search` and `fetch` are registered by Cloud only.
  425. Local diagnostics use `bm doctor`.
  426. Most tools default to text; `bm_context` defaults to JSON. Pass
  427. `output_format="json"` for structured responses. Project-scoped tools accept a
  428. name, `workspace/project`, or external UUID through `project`.
  429. Use `bm_man(page="bm-search(3)")` for the installed contract, or see the
  430. [tool guide](docs/ai-assistant-guide-extended.md). CLI commands retain their shell names.
  431. ## CLI essentials
  432. ```bash
  433. # Projects
  434. basic-memory project list
  435. basic-memory project add research ~/research
  436. basic-memory project set-cloud research # route through cloud
  437. basic-memory project set-local research # revert
  438. # Config
  439. basic-memory config list # all settings, effective values, env overrides
  440. basic-memory config set cli_output_style plain # validated through the config model
  441. basic-memory config unset cli_output_style # revert to default
  442. # Health & maintenance
  443. basic-memory status
  444. basic-memory doctor # report project problems and the commands that fix them
  445. basic-memory tool edit ... # CLI access to MCP tools
  446. basic-memory update # check for and install updates
  447. # Imports
  448. basic-memory import claude conversations
  449. basic-memory import chatgpt
  450. basic-memory import memory-json
  451. ```
  452. Routing flags (`--local` / `--cloud`) force a target when you're in mixed
  453. mode. Full CLI reference in the
  454. [docs](https://docs.basicmemory.com/reference/cli-reference?utm_source=github&utm_medium=referral&utm_campaign=readme).
  455. ## Auto-updates
  456. CLI installs check for updates every 24 hours by default and apply them
  457. silently (so the MCP server keeps responding).
  458. - Supported install sources: `uv tool`, Homebrew
  459. - Skipped for `uvx` (ephemeral runtime managed by uv)
  460. - Manual: `bm update` (check + apply) or `bm update --check` (check only)
  461. Disable in `~/.basic-memory/config.json`:
  462. ```json
  463. { "auto_update": false }
  464. ```
  465. ## Telemetry
  466. Minimal, anonymous events to understand the CLI-to-cloud conversion funnel.
  467. **What we collect:** cloud promo impressions, cloud login attempts and
  468. outcomes, promo opt-out events.
  469. **What we don't:** file contents, note titles, knowledge base data, PII, IP
  470. addresses, per-command or per-tool tracking.
  471. Events go to our [Umami Cloud](https://umami.is) instance (open-source,
  472. privacy-focused) on a background thread — never blocks the CLI.
  473. Opt out:
  474. ```bash
  475. export BASIC_MEMORY_NO_PROMOS=1
  476. ```
  477. This disables promos and all telemetry.
  478. ## Logging
  479. Basic Memory uses [Loguru](https://github.com/Delgan/loguru). Defaults vary
  480. by entry point:
  481. | Entry point | Default | Why |
  482. |---|---|---|
  483. | CLI commands | File only | Doesn't interfere with command output |
  484. | MCP server | File only | Stdout would corrupt JSON-RPC |
  485. | API server | File (local) or stdout (cloud) | Docker/cloud uses stdout |
  486. Log file: `~/.basic-memory/basic-memory.log` (10MB rotation, 10 days
  487. retention).
  488. ### Environment variables
  489. | Variable | Default | Description |
  490. |---|---|---|
  491. | `BASIC_MEMORY_LOG_LEVEL` | `INFO` | DEBUG / INFO / WARNING / ERROR |
  492. | `BASIC_MEMORY_CLOUD_MODE` | `false` | API logs to stdout with structured context |
  493. | `BASIC_MEMORY_FORCE_LOCAL` | `false` | Force local API routing |
  494. | `BASIC_MEMORY_FORCE_CLOUD` | `false` | Force cloud API routing |
  495. | `BASIC_MEMORY_EXPLICIT_ROUTING` | `false` | Mark route selection as explicit |
  496. | `BASIC_MEMORY_ENV` | `dev` | Set to `test` for test mode (stderr only) |
  497. | `BASIC_MEMORY_NO_PROMOS` | `false` | Disable cloud promos and telemetry |
  498. | `BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES` | `104857600` | Max uploaded import size |
  499. ```bash
  500. BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory reindex
  501. tail -f ~/.basic-memory/basic-memory.log
  502. ```
  503. ## Development
  504. Basic Memory supports SQLite (default, fast, no Docker) and Postgres
  505. (via testcontainers — Docker required).
  506. ```bash
  507. just install # Install with dev dependencies
  508. just test-sqlite # All tests, SQLite
  509. just test-postgres # All tests, Postgres (testcontainers)
  510. just test # Both backends
  511. just fast-check # fix/format/typecheck + impacted tests
  512. just doctor # File <-> DB consistency check (temp config)
  513. just package-check # Claude Code, skills, Hermes, OpenClaw package checks
  514. just lint
  515. just typecheck # Pyright (primary)
  516. just typecheck-ty # ty (supplemental)
  517. just format
  518. just check # All quality checks
  519. just migration "msg" # New Alembic migration
  520. ```
  521. Tests use pytest markers: `windows`, `benchmark`, `smoke`. See
  522. [justfile](justfile) for the full list.
  523. Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
  524. ## License
  525. [AGPL-3.0](LICENSE).
  526. Built with ♥️ by [Basic Machines](https://basicmachines.co?utm_source=github&utm_medium=referral&utm_campaign=readme)

Ratings and comments

Sign in to rate this skill.

Sign in

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