basic-memory 0.22.0__tar.gz → 0.22.1__tar.gz

{basic_memory-0.22.0 → basic_memory-0.22.1}/.claude/commands/release/release.md

@@ -28,7 +28,10 @@ You are an expert release manager for the Basic Memory project. When the user ru
 
 #### Documentation Validation
 1. **Changelog Check**
-   - CHANGELOG.md contains entry for target version
+   - CHANGELOG.md contains entry for target version **already landed on `main`**
+     (main only accepts changes via PR, so the changelog entry must go through
+     its own PR before running the release; the recipe pre-flight-checks for a
+     `## vX.Y.Z` heading)
    - Entry includes all major features and fixes
    - Breaking changes are documented
 
@@ -41,11 +44,15 @@ just release <version>
 The justfile target handles:
 - ✅ Version format validation
 - ✅ Git status and branch checks
-- ✅ Quality checks (`just check` - lint, format, type-check, tests)
+- ✅ Changelog entry check (must already be on `main`)
+- ✅ Quality checks (`just lint` + `just typecheck`)
 - ✅ Version update across all consolidated manifests via `just set-version` (Python
   package + Claude Code plugin/marketplaces + Codex plugin + Hermes + OpenClaw)
-- ✅ Automatic commit with proper message
-- ✅ Tag creation and pushing to GitHub
+- ✅ Release PR: commits the bump on a `release/vX.Y.Z` branch, opens a PR
+  (`chore(core): release vX.Y.Z`), and rebase-merges it — the `main` ruleset
+  rejects direct pushes and the repo disallows merge commits
+- ✅ Tags the rebased bump commit on `main` (found by commit subject, since
+  the rebase rewrites the SHA) and pushes the tag
 - ✅ Release workflow trigger (automatic on tag push)
 
 The GitHub Actions workflow (`.github/workflows/release.yml`) then:
@@ -89,7 +96,7 @@ After PyPI release is published, update the MCP registry:
 
 2. **Publish to MCP Registry**
    ```bash
-   cd /Users/drew/code/basic-memory
+   # from the basic-memory repo root
    mcp-publisher publish
    ```
 
@@ -109,7 +116,7 @@ After PyPI release is published, update the MCP registry:
 
 #### Website Updates
 
-**1. basicmachines.co** (`/Users/drew/code/basicmachines.co`)
+**1. basicmachines.co** (sibling `basicmachines.co` repo)
    - **Goal**: Update version number displayed on the homepage
    - **Location**: Search for "Basic Memory v0." in the codebase to find version displays
    - **What to update**:
@@ -126,26 +133,31 @@ After PyPI release is published, update the MCP registry:
      7. Push branch: `git push origin release/v{VERSION}`
    - **Deploy**: Follow deployment process for basicmachines.co
 
-**2. docs.basicmemory.com** (`/Users/drew/code/docs.basicmemory.com`)
-   - **Goal**: Add new release notes section to the latest-releases page
-   - **File**: `src/pages/latest-releases.mdx`
+**2. docs.basicmemory.com** (sibling `docs.basicmemory.com` repo)
+   - **Goal**: Add a What's New page for the release and bump the homepage badge
+   - **Site shape**: Nuxt/Docus content site. The changelog page
+     (`content/2.whats-new/*.changelog.md`) auto-fetches GitHub releases — no
+     manual changelog update needed. See that repo's CLAUDE.md "Version Bump
+     Checklist".
    - **What to do**:
      1. Pull latest from GitHub: `git pull origin main`
      2. Create release branch: `git checkout -b release/v{VERSION}`
-     3. Read the existing file to understand the format and structure
-     4. Read `/Users/drew/code/basic-memory/CHANGELOG.md` to get release content
-     5. Add new release section **at the top** (after MDX imports, before other releases)
-     6. Follow the existing pattern:
-        - Heading: `## [v{VERSION}](github-link) — YYYY-MM-DD`
-        - Focus statement if applicable
-        - `<Info>` block with highlights (3-5 key items)
-        - Sections for Features, Bug Fixes, Breaking Changes, etc.
-        - Link to full changelog at the end
-        - Separator `---` between releases
-     7. Commit changes: `git commit -m "docs: add v{VERSION} release notes"`
-     8. Push branch: `git push origin release/v{VERSION}`
-   - **Source content**: Extract and format sections from CHANGELOG.md for this version
-   - **Deploy**: Follow deployment process for docs.basicmemory.com
+     3. Read `CHANGELOG.md` in the `basic-memory` repo to get release content
+     4. **New minor/major release**: add `content/2.whats-new/1.v{VERSION}.md`
+        modeled on the previous version page (frontmatter title/description,
+        headline feature first, then sections, then an Upgrading note) and
+        renumber the existing what's-new pages down one slot (URLs don't
+        change — Nuxt strips the numeric prefixes)
+     5. **Patch release**: append a short note to the current version's page
+        instead of creating a new one
+     6. Update the homepage version badge in `content/index.md` (the
+        `v0.XX →` button text and its `to: /whats-new/v{VERSION}` link)
+     7. If the release adds user-facing features, update the relevant guide
+        and reference pages (`content/3.cloud/`, `content/9.reference/`)
+     8. Commit: `git commit -s -m "docs: add v{VERSION} release notes"`
+     9. Push branch and open a PR; merge after the release is tagged
+   - **Deploy**: push to main auto-deploys to development; production requires
+     manual workflow dispatch via GitHub Actions
 
 **4. Announce Release**
    - Post to Discord community if significant changes

{basic_memory-0.22.0 → basic_memory-0.22.1}/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official Basic Memory plugins from the canonical basic-memory repository",
-    "version": "0.22.0"
+    "version": "0.22.1"
   },
   "plugins": [
     {
       "name": "basic-memory",
       "source": "./plugins/claude-code",
       "description": "The bridge between Claude's working memory and Basic Memory's durable knowledge graph \u2014 session briefings, pre-compaction checkpoints, and capture reflexes",
-      "version": "0.22.0",
+      "version": "0.22.1",
       "author": {
         "name": "Basic Machines"
       },

{basic_memory-0.22.0 → basic_memory-0.22.1}/AGENTS.md

@@ -300,7 +300,9 @@ See SPEC-16 for full context manager refactor details.
 
 ### Release Process
 
-Releases are driven by `just release` / `just beta` — never by a bare `git tag`. The recipes bump version metadata, run pre-flight checks, commit, tag, and push. GitHub Actions then publishes to PyPI and updates the Homebrew formula.
+Releases are driven by `just release` / `just beta` — never by a bare `git tag`. The recipes bump version metadata, run pre-flight checks, land the bump on `main` through a release PR, tag, and push the tag. GitHub Actions then publishes to PyPI and updates the Homebrew formula.
+
+**Main requires PRs.** The `main` ruleset rejects direct pushes ("Changes must be made through a pull request") and the repo disallows merge commits, so the recipes push a `release/vX.Y.Z` branch, open a PR titled `chore(core): release vX.Y.Z`, rebase-merge it with `gh pr merge --rebase`, then tag the rebased bump commit on `main` (located by its commit subject, since rebasing rewrites the SHA) and push the tag. The CHANGELOG entry for the version must already be on `main` — land it via a normal PR before running the recipe (it pre-flight-checks for a `## vX.Y.Z` heading).
 
 **Stable release:**
 
@@ -308,7 +310,7 @@ Releases are driven by `just release` / `just beta` — never by a bare `git tag
 just release v0.21.3
 ```
 
-The recipe runs `just lint` + `just typecheck`, then updates every release manifest through `scripts/update_versions.py`: `src/basic_memory/__init__.py`, `server.json`, the root Claude marketplace, the Claude Code plugin manifest and local marketplace, the Hermes `plugin.yaml`, and the OpenClaw `package.json`. It commits as `chore: update version to X.Y.Z for vX.Y.Z release`, creates the `vX.Y.Z` tag, and pushes both the commit and the tag to `origin/main`. After the tag lands, the `Release` workflow builds the Python package, publishes to PyPI, creates the GitHub release with auto-generated notes, publishes the OpenClaw npm package, and updates the Homebrew formula. The recipe finishes by printing the post-release tasks the workflow doesn't cover.
+The recipe runs `just lint` + `just typecheck`, then updates every release manifest through `scripts/update_versions.py`: `src/basic_memory/__init__.py`, `server.json`, the root Claude marketplace, the Claude Code plugin manifest and local marketplace, the Hermes `plugin.yaml`, and the OpenClaw `package.json`. It commits as `chore: update version to X.Y.Z for vX.Y.Z release` on a `release/vX.Y.Z` branch, lands it on `main` via a rebase-merged PR, then tags the rebased commit and pushes the tag. After the tag lands, the `Release` workflow builds the Python package, publishes to PyPI, creates the GitHub release with auto-generated notes, publishes the OpenClaw npm package, and updates the Homebrew formula. The recipe finishes by printing the post-release tasks the workflow doesn't cover.
 
 **Beta release:** `just beta v0.21.3b1` — same flow with a beta-suffixed tag. PyPI consumers install with `pip install basic-memory --pre`.
 
@@ -319,7 +321,7 @@ The recipe runs `just lint` + `just typecheck`, then updates every release manif
 **Do not tag releases by hand.** A bare `git tag vX.Y.Z` skips the in-code version bump. Package metadata is still correct (uv-dynamic-versioning derives it from the git tag) but `basic-memory --version` reports the previous release, which is what happened with v0.21.2 → v0.21.3.
 
 **Post-release tasks** the recipe surfaces but doesn't run:
-- `docs.basicmemory.com` — add notes to `src/pages/latest-releases.mdx`
+- `docs.basicmemory.com` — add a What's New page under `content/2.whats-new/` and bump the version badge in `content/index.md` (the changelog page auto-fetches GitHub releases; see that repo's CLAUDE.md version-bump checklist)
 - `basicmachines.co` — bump version in `src/components/sections/hero.tsx`
 - MCP Registry — `mcp-publisher publish` from the repo root
 

{basic_memory-0.22.0 → basic_memory-0.22.1}/CHANGELOG.md

@@ -1,5 +1,49 @@
 # CHANGELOG
 
+## v0.22.1 (2026-06-12)
+
+Follow-up patch to v0.22.0. Fixes project and default-project resolution on
+fresh installs, MCP workspace routing, sync project selection, and CLI startup
+latency, plus a few MCP parity additions.
+
+### Features
+
+- Added a `workspace` parameter to `write_note` for parity with `edit_note`.
+- **#826**: Added `title` and `tags` annotations to all MCP tool decorators
+  (phase 1).
+- **#930**: `search_notes` now comma-splits `note_types`, `entity_types`, and
+  `categories`.
+- **#971**: Added the manual-pages flow — manpage seed schema, flow docs, and
+  verification fixes.
+
+### Bug Fixes
+
+- Fresh installs no longer fail when the projects table is empty: resolve now
+  points them at project setup, the first project is promoted to default when
+  the config default is missing from the database, the promoted default state
+  is returned from the project-create API, and a default can be set when none
+  is currently set. An existing database default is preserved when repairing a
+  missing config default.
+- **#949**: Sync skips projects without an absolute local path and excludes
+  orphan DB projects that are absent from config.
+- **#952 / #981**: Resolved workspace display names and tenant ids in qualified
+  project routes, closing out the manual verification findings.
+- `note_types`/`entity_types`/`categories` are normalized on the direct-call
+  path, with non-string list elements rejected.
+- Vector-search hydration keys on `(type, id)` to prevent id collisions.
+- `file_utils` requires line-anchored frontmatter fences.
+- CLI startup is faster: FastAPI and app imports are deferred out of CLI
+  startup, and rich/typer modules are preloaded before an in-place upgrade.
+- `config.json` is written atomically.
+- In-memory SQLite sessions are serialized so concurrent rollbacks cannot
+  destroy writes.
+
+### Maintenance
+
+- Release recipes route through PRs and wait for the release PR merge to land
+  before tagging; the release runbook is refreshed and stripped of
+  user-specific absolute paths.
+
 ## v0.22.0 (2026-06-11)
 
 Team-safe cloud sync. New additive `bm cloud push` and `bm cloud pull`

{basic_memory-0.22.0 → basic_memory-0.22.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basic-memory
-Version: 0.22.0
+Version: 0.22.1
 Summary: Local-first knowledge management combining Zettelkasten with knowledge graphs
 Project-URL: Homepage, https://github.com/basicmachines-co/basic-memory
 Project-URL: Repository, https://github.com/basicmachines-co/basic-memory
@@ -645,7 +645,7 @@ retention).
 | `BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES` | `104857600` | Max uploaded import size |
 
 ```bash
-BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory sync
+BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory reindex
 tail -f ~/.basic-memory/basic-memory.log
 ```
 

{basic_memory-0.22.0 → basic_memory-0.22.1}/README.md

@@ -590,7 +590,7 @@ retention).
 | `BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES` | `104857600` | Max uploaded import size |
 
 ```bash
-BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory sync
+BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory reindex
 tail -f ~/.basic-memory/basic-memory.log
 ```
 

{basic_memory-0.22.0 → basic_memory-0.22.1}/docs/Docker.md

@@ -111,7 +111,7 @@ You can run Basic Memory CLI commands inside the container using `docker exec`:
 docker exec basic-memory-server basic-memory status
 
 # Sync files
-docker exec basic-memory-server basic-memory sync
+docker exec basic-memory-server basic-memory reindex
 
 # Show help
 docker exec basic-memory-server basic-memory --help
@@ -137,7 +137,7 @@ When using Docker volumes, you'll need to configure projects to point to your mo
 
 3. **Sync the new project:**
    ```bash
-   docker exec basic-memory-server basic-memory sync
+   docker exec basic-memory-server basic-memory reindex
    ```
 
 ### Example: Setting up an Obsidian Vault
@@ -157,7 +157,7 @@ docker exec basic-memory-server basic-memory project create obsidian /app/data
 docker exec basic-memory-server basic-memory project set-default obsidian
 
 # Sync to index all files
-docker exec basic-memory-server basic-memory sync
+docker exec basic-memory-server basic-memory reindex
 ```
 
 ### Environment Variables

{basic_memory-0.22.0 → basic_memory-0.22.1}/docs/character-handling.md

@@ -184,8 +184,8 @@ finance/           (lowercase f)
 Use Basic Memory's built-in conflict detection:
 
 ```bash
-# Sync will report conflicts
-basic-memory sync
+# Index local file changes (conflicts are handled during the scan)
+basic-memory reindex
 
 # Check sync status for warnings
 basic-memory status

basic_memory-0.22.1/docs/manual-pages.md

@@ -0,0 +1,183 @@
+# Manual Pages
+
+Basic Memory's manual is written in the style of Unix man pages — and
+implemented as Basic Memory notes ([#952](https://github.com/basicmachines-co/basic-memory/issues/952)).
+Every page is a markdown note conforming to the `Manpage` schema, `SEE ALSO`
+entries are real knowledge-graph relations, and every example on every page
+was executed against a live project before the page shipped. The manual
+documents the tools; the tools verify the manual.
+
+## Where it lives
+
+The canonical manual is the **`manual` project in the Basic Memory team
+workspace** (cloud, shared). Anyone can build their own: the schema ships as
+an opt-in seed at `plugins/claude-code/schemas/manpage.md` — copy it into any
+project's folder and start writing pages against it.
+
+Layout:
+
+```
+manual/
+├── schemas/Manpage.md      # the manpage schema (type: schema)
+├── man1/                   # CLI commands        bm(1), bm-status(1), ...
+├── man3/                   # MCP tools           write-note(3), search-notes(3), ...
+├── man5/                   # file formats        bm-note(5), bm-observation(5), ...
+├── man7/                   # concepts            basic-memory(7), semantic-memory(7), ...
+├── playground/             # scratch notes for destructive examples
+└── diagrams/               # canvas visualizations of the manual graph
+```
+
+### Why "man1", "man3", "man5"?
+
+The folder names are Unix's, unchanged since 1971. The manual is divided
+into numbered **sections**, pages physically live in directories named
+after them (`/usr/share/man/man1`, `man5`, ...), and the number tells you
+what *kind* of thing is documented — not importance, not reading order:
+
+- **1** — user commands (`ls`, `grep`)
+- **2** — system calls
+- **3** — library functions / APIs (`printf(3)`)
+- **4** — devices
+- **5** — file formats and config files (`crontab(5)`, `passwd(5)`)
+- **6** — games (really)
+- **7** — miscellanea: concepts, conventions, overviews (`regex(7)`, `signal(7)`)
+- **8** — system administration
+
+That's also why man page names carry the parenthesized number —
+`crontab(1)` is the command, `crontab(5)` is the file format, same name in
+two sections. `man 5 crontab` picks the section explicitly.
+
+This manual copies that layout with the sections that have a Basic Memory
+analog:
+
+- **man1/** — `bm` CLI commands → `bm-status(1)`
+- **man3/** — MCP tools, our equivalent of the "library API" section → `write-note(3)`
+- **man5/** — file formats: note syntax, observations, relations, schemas → `bm-note(5)`
+- **man7/** — concepts → `basic-memory(7)`, `semantic-memory(7)`
+- **8** is reserved for admin/cloud operations but has no pages yet; 2, 4,
+  and 6 have no analog (no system calls, no devices, and no games — yet)
+
+When a page says `see_also [[bm-note(5)]]`, the `(5)` reads "the
+file-format page," exactly the way a Unix manual cross-references — except
+here it's a traversable relation in the graph instead of a typographic
+convention. The manual explains its own conventions in `man-pages(7)` —
+fittingly, the same page name Linux uses for this, and that almost nobody
+ever reads.
+
+## Page anatomy
+
+Pages use the classic headers where applicable: `NAME`, `SYNOPSIS`,
+`DESCRIPTION`, `PARAMETERS`, `MCP USAGE`, `CLI EQUIVALENT`, `EXAMPLES`,
+`GOTCHAS`, `SEE ALSO`. Frontmatter (validated by the schema):
+
+```yaml
+type: manpage
+section: 3                      # 1 | 3 | 5 | 7 | 8
+name: write-note                # page name without section suffix
+summary: create or overwrite a markdown note in the knowledge base
+generated: hand                 # hand | registry | typer  (regeneration ownership)
+tool: write_note                # section-3 pages: the MCP tool documented
+command: basic-memory status    # section-1 pages: the CLI command documented
+verified: 0.21.6 mcp+cli        # version + path(s) that proved the page
+```
+
+Field knowledge accumulates as observations — `[gotcha]`, `[bug]` (with issue
+links), `[pattern]` — and `SEE ALSO` entries are `see_also` relations, so the
+manual is a navigable graph, not a folder of files.
+
+## How to use it
+
+Man-style reads (any MCP client or the CLI):
+
+```bash
+# read a page
+bm tool read-note "man3/write-note-3" --project manual
+
+# apropos — find pages by section, tool, or text
+bm tool search-notes --project manual          # then filter, or via MCP:
+#   search_notes(project="manual", metadata_filters={"type": "manpage", "section": 3})
+#   search_notes(project="manual", metadata_filters={"type": "manpage", "tool": "write_note"})
+
+# traverse SEE ALSO from any page
+#   build_context(url="man3/write-note-3", project="manual")
+```
+
+A future `bm man <topic>` command is thin sugar over exactly these calls.
+
+And for the real thing — `man bm` in an actual terminal:
+
+```bash
+bm man install        # copies bundled groff pages to ~/.local/share/man
+man bm                # the overview page, rendered by man(1)
+man basic-memory      # same page via its alias
+```
+
+`bm man install` warns with a one-line `MANPATH` fix if the install root
+isn't searched by your `man`. Agents with shell access can use `man bm` as
+an offline quick reference; the full per-tool detail stays in the manual
+project's section-3 pages.
+
+## The verification discipline
+
+Two rules make the manual trustworthy:
+
+1. **Examples must have run.** An `EXAMPLES` (or `MCP USAGE` / `CLI
+   EQUIVALENT`) block contains only commands that actually executed against
+   the manual project. Destructive operations (`delete_note`, `move_note`,
+   destructive `edit_note`) run only against `playground/` notes — never
+   against pages. The `verified:` field records the version and which path
+   proved the page: `mcp` (live service), `cli` (dev checkout), or both.
+
+2. **The schema is the linter.** Validate the whole manual any time:
+
+   ```bash
+   bm tool schema-validate manpage --project manual
+   # → {"total_notes": 38, "valid_count": 38, "warning_count": 0, ...}
+   ```
+
+   `bm orphans --project manual` confirms every page is connected to the
+   graph, and `schema_diff`/`schema_infer` report drift between the schema
+   and how pages are actually written.
+
+Because verification exercises real tool calls against the live service,
+building the manual doubles as an end-to-end smoke test. The initial build
+found six bugs in one pass (#954–#959) — including the verification rule
+catching a test that asserted a bug as expected output (#958).
+
+## Adding or updating a page
+
+1. Run the commands you intend to document; keep the actual output.
+2. Write the page with `write_note`, passing frontmatter through the
+   `metadata` parameter (nested YAML in content frontmatter is unreliable on
+   some clients):
+
+   ```
+   write_note(title="my-tool(3)", directory="man3", project="manual",
+              note_type="manpage",
+              metadata={"section": 3, "name": "my-tool",
+                        "summary": "...", "generated": "hand",
+                        "tool": "my_tool", "verified": "<version> mcp"})
+   ```
+
+3. Link related pages in `SEE ALSO` with `see_also [[other-page(3)]]`.
+   Forward references to pages that don't exist yet are fine — they resolve
+   automatically when the target is written.
+4. Validate: `bm tool schema-validate manpage --project manual`.
+
+For mechanical updates to generated sections, prefer `edit_note` with
+`replace_section` / `insert_after_section` so curated content (EXAMPLES,
+GOTCHAS, SEE ALSO, observations) survives — that ownership split is what the
+`generated:` field declares.
+
+## Roadmap
+
+- **Registry generator** — section-3 SYNOPSIS/PARAMETERS generated from the
+  MCP tool registry (docstrings + pydantic schemas), section-1 from Typer
+  help; the hand-written corpus is the template spec. Regenerate-and-diff in
+  CI becomes the drift gate.
+- **`bm man <topic>`** — CLI sugar over `read_note` + metadata search.
+  (`bm man install` + a hand-written `bm.1` already ship — the first slice
+  of [#610](https://github.com/basicmachines-co/basic-memory/issues/610);
+  the generator will produce per-command pages from the same extraction.)
+- **Docs site** — the notes remain canonical for sections 5 and 7, code is
+  canonical for 1 and 3; both render to the hosted docs site.

{basic_memory-0.22.0 → basic_memory-0.22.1}/integrations/hermes/__init__.py

@@ -38,7 +38,7 @@ from typing import Any, Callable
 from agent.memory_provider import MemoryProvider
 from tools.registry import tool_error
 
-__version__ = "0.22.0"
+__version__ = "0.22.1"
 
 logger = logging.getLogger("hermes.memory.basic-memory")
 

{basic_memory-0.22.0 → basic_memory-0.22.1}/integrations/hermes/plugin.yaml

@@ -1,5 +1,5 @@
 name: basic-memory
-version: 0.22.0
+version: 0.22.1
 description: "Basic Memory — persistent knowledge graph backed by the basic-memory MCP server"
 pip_dependencies:
   - mcp

{basic_memory-0.22.0 → basic_memory-0.22.1}/integrations/openclaw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",