git:20260828.352f43f to git:20260828.5836c45

# AGENTS.md - Basic Memory Project Guide

## Project Overview

Basic Memory is a local-first knowledge management system built on the Model Context Protocol (MCP). It enables

bidirectional communication between LLMs (like Claude) and markdown files, creating a personal knowledge graph that can

be traversed using links between documents.

## CODEBASE DEVELOPMENT

### Project information

See the [README.md](README.md) file for a project overview.

### Build and Test Commands

- Install: `just install` or `pip install -e ".[dev]"`

- Run all tests (SQLite + Postgres): `just test`

- Run all tests against SQLite: `just test-sqlite`

- Run all tests against Postgres: `just test-postgres` (uses testcontainers)

- Run unit tests (SQLite): `just test-unit-sqlite`

- Run unit tests (Postgres): `just test-unit-postgres`

- Run integration tests (SQLite): `just test-int-sqlite`

- Run integration tests (Postgres): `just test-int-postgres`

- Run impacted tests: `just fast-test` or `just testmon` (pytest-testmon; only tests affected by changed code)

- Run MCP smoke test: `just test-smoke`

- Fast static check: `just fast-check` (fix, format, typecheck)

- Fast test loop: `just fast-test` (pytest-testmon impacted tests)

- Local consistency check: `just doctor`

- Run all consolidated agent package checks: `just package-check`

- Run Claude Code plugin checks: `just package-check-claude-code`

- Run shared skills checks: `just package-check-skills`

- Run Hermes plugin checks: `just package-check-hermes`

- Run OpenClaw plugin checks: `just package-check-openclaw`

- Run host-native agent harness checks: `just agent-harness-check`

- Generate HTML coverage: `just coverage`

- Single test: `pytest tests/path/to/test_file.py::test_function_name`

- Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`

- Lint: `just lint` or `ruff check . --fix`

- Type check: `just typecheck` or `uv run ty check src tests test-int`

- Type check (pyright): `just typecheck-pyright` or `uv run pyright`

- Format: `just format` or `uv run ruff format .`

- Run all static code checks: `just check` (runs lint, format, typecheck)

- Create db migration: `just migration "Your migration message"`

- Run development MCP Inspector: `just run-inspector`

**Note:** Project requires Python 3.12+ (uses type parameter syntax and `type` aliases introduced in 3.12)

**Postgres Testing:** Uses [testcontainers](https://testcontainers-python.readthedocs.io/) which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.

**Doctor Note:** `just doctor` runs with a temporary HOME/config so it won't touch your local Basic Memory settings. It leaves temp dirs in `/tmp` (safe to ignore or remove).

**Testmon Note:** When no files have changed, `just testmon` may collect 0 tests. That's expected and means no impacted tests were detected.

### Code/Test/Verify Loop (fast path)

1) **Code:** make changes.

2) **Check:** `just fast-check` (fix, format, typecheck; no tests).

3) **Test:** `just fast-test` for pytest-testmon impacted tests, or a targeted `uv run pytest ...` command.

4) **Verify:** `just doctor` (end-to-end file ↔ DB loop in a temp project).

5) **Package verify:** `just package-check` when changes touch `plugins/`, `skills/`, `integrations/`, package metadata, or release wiring.

6) **Full gate (when needed):** `just test` for SQLite + Postgres.

Run `just test-smoke` when you specifically need the MCP smoke flow.

If testmon is “cold,” the first run may be long. Subsequent runs get much faster.

### Consolidated Agent Package Checks

The monorepo ships several host-native packages alongside the Python core. Use the root justfile as the canonical entry point:

- `just package-check` — validates every copied package and generated bundle path.

- `just package-check-claude-code` — validates the root and plugin-local Claude marketplace manifests, the SessionStart/PreCompact hooks, the bundled output style, and the seed schemas, then runs `claude plugin validate . --strict`.

- `just package-check-skills` — validates every top-level `skills/memory-*/SKILL.md` frontmatter block.

- `just package-check-hermes` — validates `integrations/hermes/plugin.yaml`, the Hermes provider entrypoint, bundled skill, and runs the hermetic unit suite.

- `just package-check-openclaw` — runs the OpenClaw package install, copies top-level skills into the generated bundle, typechecks, lints, builds `dist/`, runs Bun tests, and performs `npm pack --dry-run`.

- `just agent-harness-check` — checks the host-specific harnesses without the shared markdown-only skills target.

Package-local justfiles live in `plugins/claude-code/`, `skills/`, `integrations/hermes/`, and `integrations/openclaw/`. Prefer the root targets for PR verification so command names stay stable as package internals evolve.

### PR CI Gate

Before opening or updating a PR, run the checks that mirror the common required CI failures:

- Run `just typecheck` in addition to targeted `ruff` and `pytest` commands when tests were added or changed.

- Sign commits with `git commit -s` so DCO passes. If a PR branch already has unsigned commits, rewrite the branch with signed-off commits before asking for review.

- Use a semantic PR title accepted by `.github/workflows/pr-title.yml`: `type(scope): summary`.

- Use one of the allowed scopes: `core`, `cli`, `api`, `mcp`, `sync`, `ui`, `ci`, `deps`, `installer`, `plugins`, `skills`, `integrations`.

### Test Structure

- `tests/` - Unit tests for individual components (mocked, fast)

- `test-int/` - Integration tests for real-world scenarios (no mocks, realistic)

- Both directories are covered by unified coverage reporting

- Benchmark tests in `test-int/` are marked with `@pytest.mark.benchmark`

- Slow tests are marked with `@pytest.mark.slow`

- Smoke tests are marked with `@pytest.mark.smoke`

### Code Style Guidelines

- Line length: 100 characters max

- Python 3.12+ with full type annotations (uses type parameters and type aliases)

- Format with ruff (consistent styling)

- Import order: standard lib, third-party, local imports

- Naming: snake_case for functions/variables, PascalCase for classes

- Prefer async patterns with SQLAlchemy 2.0

- Use Pydantic v2 for data validation and schemas

- CLI uses Typer for command structure

- API uses FastAPI for endpoints

- Follow the repository pattern for data access

- Tools communicate to api routers via the httpx ASGI client (in process)

### Programming Style

See [docs/ENGINEERING_STYLE.md](docs/ENGINEERING_STYLE.md) for the fuller house style and

[docs/DOMAIN_MODEL.md](docs/DOMAIN_MODEL.md) for product language, ownership, identity, and

source-of-truth rules. The short version for agents:

For nontrivial Python writing, refactoring, or review, read and follow

[`.agents/skills/pythonic-code/SKILL.md`](.agents/skills/pythonic-code/SKILL.md) in full. Use

the skill's Write, Refactor, or Review mode that matches the task. GitHub coding and review

agents must apply this skill before changing or evaluating Python code.

- Prefer type-safe, explicit designs over object-heavy indirection. Use Python 3.12 `type`

aliases, full annotations, and narrow `Protocol`s when a caller only needs a capability.

- Prefer functions and typed values before classes, and concrete classes before abstract base

classes. Treat private-helper sprawl as a prompt to simplify the data flow.

- Use dataclasses for internal value objects and operation results; use Pydantic v2 at API,

CLI, MCP, and persistence boundaries where validation and serialization matter.

- Keep async boundaries obvious. Resource-owning code should use context managers, propagate

cancellation, and avoid hidden background work unless the lifecycle is explicit.

- Fail fast. Do not add silent fallback logic, broad exception swallowing, speculative

`getattr`, or casts that hide an unclear model shape.

- Keep control flow simple and local. Push branching decisions up, keep leaf helpers focused,

and name values after the domain concept they carry.

- Use evidence-first testing. Add or update meaningful regression tests for bugs and risky

behavior, prefer real code paths over mocks, and run the narrowest command that proves the

change before widening verification.

- Comments should explain why a branch, invariant, or constraint exists. Avoid comments that

merely narrate obvious code.

### Code Change Guidelines

- **Full file read before edits**: Before editing any file, read it in full first to ensure complete context; partial reads lead to corrupted edits

- **Minimize diffs**: Prefer the smallest change that satisfies the request. Avoid unrelated refactors or style rewrites unless necessary for correctness

- **House style is canonical**: Follow the Programming Style section above for type-safe,

fail-fast code; do not hide unclear models with speculative attributes, broad exception

handling, casts, or unapproved fallback logic

- **No guessing**: Do not say "The issue is..." before you actually know what the issue is. Investigate first.

### Consistency Model — Review Expectations

Basic Memory separates canonical state from derived state, and reviews (human or automated)

must hold them to different standards:

- **Canonical state** — the markdown bytes of a note (on disk and as accepted

`note_content`). Writes are guarded: CAS on `db_version`, generation fences,

checksum-guarded file operations. Corrupting, wrongly rewriting, or wrongly deleting note

content is always a real finding, in every code path — materialization writes canonical

bytes into their portable file form, so the file's *content* is never "just a projection".

- **Derived state** — entity file metadata, observation/relation graph rows, search index

rows, and materialization status/lineage (file versions, checksums, write status, *when*

a file catches up to its accepted row). This is **eventually consistent by design**. It

converges through the next write, the next index pass, `reindex`, or the scheduled orphan

sweeper (cloud). Stale writers no-op on generation fences instead of blocking; concurrent

races resolve last-writer-wins.

Deadlocks are always worse than temporary staleness. Do NOT raise review findings that

propose, for derived-state paths:

- adding `SELECT ... FOR UPDATE` or wider/shared transactions — this class of "fix" caused

the production deadlock clusters (#1213, #1224) and the silent observation duplication

(#1214). (Code that legitimately takes locks must still follow the canonical

NoteContent-first order documented by `current_relation_generation_statement`; flagging a

violation of that ordering IS a real finding — the ban is on adding serialization, not on

policing the existing protocol.);

- adding compensating re-checks, retry markers, or two-phase machinery for races whose

drift self-heals on a later write or index pass;

- treating a window where a projection lags its canonical source as a bug, including rare

transient-failure windows that a later edit, `reindex`, or the orphan sweeper repairs.

(`doctor` diagnoses in a temporary project; it is not a repair mechanism and does not

count as one.)

A derived-state race is a real finding only when it converges to a *wrong* state that no

existing mechanism repairs, with a realistically hittable window. Name that non-converging

end state explicitly and the mechanism gap; otherwise do not raise it. When in doubt,

prefer the smaller, lock-free design and note the alternative in the PR discussion instead

of a review finding.

### Literate Programming Style

Code should tell a story. Comments must explain the "why" and narrative flow, not just the "what".

**Section Headers:**

For files with multiple phases of logic, add section headers so the control flow reads like chapters:

```python

# --- Authentication ---

# ... auth logic ...

# --- Data Validation ---

# ... validation logic ...

# --- Business Logic ---

# ... core logic ...

```

**Decision Point Comments:**

For conditionals that materially change behavior (gates, fallbacks, retries, feature flags), add comments with:

- **Trigger**: what condition causes this branch

- **Why**: the rationale (cost, correctness, UX, determinism)

- **Outcome**: what changes downstream

```python

# Trigger: project has no active sync watcher

# Why: avoid duplicate file system watchers consuming resources

# Outcome: starts new watcher, registers in active_watchers dict

if project_id not in active_watchers:

start_watcher(project_id)

```

**Constraint Comments:**

If code exists because of a constraint (async requirements, rate limits, schema compatibility), explain the constraint near the code:

```python

# SQLite requires WAL mode for concurrent read/write access

connection.execute("PRAGMA journal_mode=WAL")

```

**What NOT to Comment:**

Avoid comments that restate obvious code:

```python

# Bad - restates code

counter += 1 # increment counter

# Good - explains why

counter += 1 # track retries for backoff calculation

```

### Codebase Architecture

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for code layers and dependency direction. See

[docs/DOMAIN_MODEL.md](docs/DOMAIN_MODEL.md) for the meaning and invariants of the concepts those

layers implement.

**Directory Structure:**

- `/alembic` - Alembic db migrations

- `/api` - FastAPI REST endpoints + `container.py` composition root

- `/cli` - Typer CLI + `container.py` composition root

- `/deps` - Feature-scoped FastAPI dependencies (config, db, projects, repositories, services, importers)

- `/importers` - Import functionality for Claude, ChatGPT, and other sources

- `/markdown` - Markdown parsing and processing

- `/mcp` - MCP server + `container.py` composition root + `clients/` typed API clients

- `/models` - SQLAlchemy ORM models

- `/picoschema` - Picoschema parsing, resolution, validation, inference, and drift

- `/repository` - Data access layer

- `/schemas` - Pydantic models for validation

- `/services` - Business logic layer

- `/index` - Local runtime indexing adapters, watch service + `watch_coordinator.py` for lifecycle management

- `/indexing` - Portable indexing runners and planners shared by local and hosted runtimes

- `/runtime` - RuntimeMode resolution + runtime Protocol contracts

- `/plugins/claude-code` - Claude Code plugin marketplace package, hooks, skills, and agent harness

- `/skills` - Canonical framework-agnostic Basic Memory `SKILL.md` source

- `/integrations/hermes` - Hermes memory-provider plugin

- `/integrations/openclaw` - OpenClaw npm/TypeScript plugin

**Composition Roots:**

Each entrypoint (API, MCP, CLI) has a composition root that:

- Reads `ConfigManager` (the only place that reads global config)

- Resolves runtime mode via `RuntimeMode` enum (TEST > CLOUD > LOCAL)

- Provides dependencies to downstream code explicitly

**Typed API Clients (MCP):**

MCP tools use typed clients in `mcp/clients/` to communicate with the API:

- `KnowledgeClient` - Entity CRUD operations

- `SearchClient` - Search operations

- `MemoryClient` - Context building

- `DirectoryClient` - Directory listing

- `ResourceClient` - Resource reading

- `ProjectClient` - Project management

Flow: MCP Tool → Typed Client → HTTP API → Router → Service → Repository

### Development Notes

- MCP tools are defined in src/basic_memory/mcp/tools/

- MCP prompts are defined in src/basic_memory/mcp/prompts/

- MCP tools should be atomic, composable operations

- Use `textwrap.dedent()` for multi-line string formatting in prompts and tools

- MCP Prompts are used to invoke tools and format content with instructions for an LLM

- Schema changes require Alembic migrations

- SQLite is used for indexing and full text search, files are source of truth

- Testing uses pytest with asyncio support (strict mode)

- Unit tests (`tests/`) use mocks when necessary; integration tests (`test-int/`) use real implementations

- By default, tests run against SQLite (fast, no Docker needed)

- Set `BASIC_MEMORY_TEST_POSTGRES=1` to run against Postgres (uses testcontainers - Docker required)

- Each test runs in a standalone environment with isolated database and tmp_path directory

- CI runs SQLite and Postgres tests in parallel for faster feedback

- Performance benchmarks are in `test-int/test_sync_performance_benchmark.py`

- Use pytest markers: `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests

- **Coverage must stay at 100%**: Write tests for new code. Only use `# pragma: no cover` when tests would require excessive mocking (e.g., TYPE_CHECKING blocks, error handlers that need failure injection, runtime-mode-dependent code paths)

### Async Client Pattern (Important!)

**MCP tools use `get_project_client()` for per-project routing:**

```python

from basic_memory.mcp.project_context import get_project_client

@mcp.tool()

async def my_tool(project: str | None = None, context: Context | None = None):

async with get_project_client(project, context) as (client, active_project):

# client is routed based on project's mode (local ASGI or cloud HTTP)

response = await call_get(client, "/path")

return response

```

**CLI commands and non-project-scoped code use `get_client()` directly:**

```python

from basic_memory.mcp.async_client import get_client

async def my_cli_command():

async with get_client() as client:

response = await call_get(client, "/path")

return response

# Per-project routing (when project name is known):

async with get_client(project_name="research") as client:

...

```

**Do NOT use:**

- ❌ `from basic_memory.mcp.async_client import client` (deprecated module-level client)

- ❌ Manual auth header management

- ❌ `inject_auth_header()` (deleted)

- ❌ Separate `get_client()` + `get_active_project()` in MCP tools (use `get_project_client()` instead)

**Key principles:**

- Auth happens at client creation, not per-request

- Proper resource management via context managers

- Per-project routing: each project can be LOCAL or CLOUD independently

- Cloud projects use API key (`cloud_api_key` in config) as Bearer token

- Routing priority: factory injection > force-local > per-project cloud > global cloud > local ASGI

- Factory pattern enables dependency injection for cloud consolidation

**For cloud app integration:**

```python

from basic_memory.mcp import async_client

# Set custom factory before importing tools

async_client.set_client_factory(your_custom_factory)

```

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, 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:**

```

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` 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`. While `pyproject.toml` pins a FastMCP pre-release, the recipe refuses to publish a beta: every documented install runs with `--prerelease=allow`, which uv applies to basic-memory itself, so a beta on PyPI would become the default install for stable users (#1338). Override deliberately with `BASIC_MEMORY_ALLOW_BETA_WITH_PRERELEASE_DEPS=1`.

**Release dry run:** `just release-dry-run v0.21.4` previews the consolidated version update without writing files.

**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 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)

- `basicmemory.com` — the marketing site (Astro + React, repo

`basicmachines-co/basicmemory.com`, formerly `basicmachines.co`) carries **no

hardcoded version number** in its UI, so there is nothing to bump. For a

significant release, optionally add a dated announcement post under

`src/content/blog/` (model it on an existing `basic-memory-vX-Y-Z-release.md`).

Skip entirely for routine patch releases.

- MCP Registry — `mcp-publisher publish` from the repo root

See `.claude/commands/release/release.md` (and `beta.md`, `release-check.md`, `changelog.md` alongside it) for the full release + post-release runbook, including the slash commands.

## BASIC MEMORY PRODUCT USAGE

### Knowledge Structure

- Project: The knowledge and isolation boundary for entities, graph state, and search

- Note: A user-facing Markdown document and the canonical representation of its knowledge

- Entity: The project-scoped indexed representation of a file or resource

- Observation: A categorized fact about an entity (`- [category] content`)

- Relation: A directed semantic link owned by its source entity (`- relation_type [[Target]]`)

- Frontmatter: YAML metadata at the top of markdown files

- Knowledge representation follows precise markdown format:

- Observations with [category] prefixes

- Relations with WikiLinks [[Entity]]

- Frontmatter with metadata

### Basic Memory Commands

**Local Commands:**

- Check sync status: `basic-memory status`

- Doctor check (file <-> DB loop): `basic-memory doctor`

- Import from Claude: `basic-memory import claude conversations`

- Import from ChatGPT: `basic-memory import chatgpt`

- Import from Memory JSON: `basic-memory import memory-json`

- Tool access: `basic-memory tool` (provides CLI access to MCP tools)

- Continue: `basic-memory tool continue-conversation --topic="search"`

**Config Management:**

- List all settings (effective values, env overrides marked): `basic-memory config list`

- Get one setting: `basic-memory config get cli_output_style`

- Set a setting (validated through the config model): `basic-memory config set cli_output_style plain`

- Revert a setting to its default: `basic-memory config unset cli_output_style`

**Project Management:**

- List projects: `basic-memory project list`

- Add project: `basic-memory project add "name" ~/path`

- Project info: `basic-memory project info`

- Set cloud mode: `basic-memory project set-cloud "name"`

- Set local mode: `basic-memory project set-local "name"`

- One-way sync (local -> cloud): `basic-memory project sync`

- Bidirectional sync: `basic-memory project bisync`

- Integrity check: `basic-memory project check`

**Cloud Commands (requires subscription):**

- Authenticate (global): `basic-memory cloud login`

- Logout (global): `basic-memory cloud logout`

- Check cloud status: `basic-memory cloud status`

- Setup cloud sync: `basic-memory cloud setup`

- Save API key: `basic-memory cloud set-key bmc_...`

- Create API key: `basic-memory cloud create-key "name"`

- Manage snapshots: `basic-memory cloud snapshot [create|list|delete|show|browse]`

- Restore from snapshot: `basic-memory cloud restore <path> --snapshot <id>`

**Cloud Sync Commands (Personal and Team workspaces):**

- Fetch cloud changes (cloud -> local): `basic-memory cloud pull --name "name"` (Team-safe; additive, never deletes local)

- Upload local changes (local -> cloud): `basic-memory cloud push --name "name"` (Team-safe; additive, never deletes cloud)

- Resolve conflicts on push/pull: `--on-conflict [fail|keep-local|keep-cloud|keep-both]` (default `fail` lists conflicts and aborts, git-style)

- One-way mirror (local -> cloud): `basic-memory cloud sync --name "name"` (Personal workspaces only; deletes cloud files missing locally)

- Two-way mirror (local <-> cloud): `basic-memory cloud bisync --name "name"` (Personal workspaces only)

### MCP Capabilities

- Basic Memory exposes these MCP tools to LLMs:

**Content Management:**

- `write_note(title, content, directory, tags)` - Create/update markdown notes with semantic observations and relations

- `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph awareness

- `read_content(path)` - Read raw file content (text, images, binaries) without knowledge graph processing

- `view_note(identifier, page, page_size)` - View notes as formatted artifacts for better readability

- `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, replace_section)

- `move_note(identifier, destination_path, is_directory)` - Move notes or directories to new locations, updating database and maintaining links

- `delete_note(identifier, is_directory)` - Delete notes or directories from the knowledge base

**Knowledge Graph Navigation:**

- `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation continuity

- `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "1d", "1 week")

- `list_directory(dir_name, depth, file_name_glob)` - Browse directory contents with filtering and depth control

**Search & Discovery:**

- `search_notes(query, page, page_size, search_type, types, entity_types, after_date)` - Full-text search across all content with advanced filtering options

**Project Management:**

- `list_memory_projects()` - List all available projects with their status

- `create_memory_project(project_name, project_path, set_default)` - Create new Basic Memory projects

- `delete_project(project_name)` - Delete a project from configuration

**ChatGPT-Compatible Tools:**

- `search(query)` - Search across knowledge base (OpenAI actions compatible)

- `fetch(id)` - Fetch full content of a search result document

- MCP Prompts for better AI interaction:

- `ai_assistant_guide()` - Guidance on effectively using Basic Memory tools for AI assistants

- `continue_conversation(topic, timeframe)` - Continue previous conversations with relevant historical context

- `search(query, after_date)` - Search with detailed, formatted results for better context understanding

- `recent_activity(timeframe)` - View recently changed items with formatted output

### Cloud Features (v0.15.0+)

Basic Memory now supports cloud synchronization and storage (requires active subscription):

**Authentication:**

- JWT-based authentication with subscription validation

- Secure session management with token refresh

- Support for multiple cloud projects

**Bidirectional Sync:**

- rclone bisync integration for two-way synchronization

- Conflict resolution and integrity verification

- Real-time sync with change detection

- Mount/unmount cloud storage for direct file access

**Cloud Project Management:**

- Create and manage projects in the cloud

- Toggle between local and cloud modes

- Per-project sync configuration

- Subscription-based access control

**Security & Performance:**

- Removed .env file loading for improved security

- .gitignore integration (respects gitignored files)

- WAL mode for SQLite performance

- Background relation resolution (non-blocking startup)

- API performance optimizations (SPEC-11)

**Per-Project Cloud Routing:**

Individual projects can be routed through the cloud while others stay local, using an API key:

```bash

# Save API key and set project to cloud mode

basic-memory cloud set-key bmc_abc123...

basic-memory project set-cloud research # route through cloud

basic-memory project set-local research # revert to local

```

MCP tools use `get_project_client()` which automatically routes based on the project's mode. Cloud projects use the `cloud_api_key` from config as Bearer token.

**CLI Routing Flags (Global Cloud Mode):**

When global cloud mode is enabled, CLI commands route to the cloud API by default. Use `--local` and `--cloud` flags to override:

```bash

# Force local routing (ignore cloud mode)

basic-memory status --local

basic-memory project list --local

# Force cloud routing (when cloud mode is disabled)

basic-memory status --cloud

basic-memory project info my-project --cloud

```

Key behaviors:

- The local MCP server (`basic-memory mcp`) automatically uses local routing

- This allows simultaneous use of local Claude Desktop and cloud-based clients

- Some commands (like `project default`, `project sync-config`, `project move`) require `--local` in cloud mode since they modify local configuration

- Environment variable `BASIC_MEMORY_FORCE_LOCAL=true` forces local routing globally

- Per-project cloud routing via API key works independently of global cloud mode

## AI-Human Collaborative Development

Basic Memory emerged from and enables a new kind of development process that combines human and AI capabilities. Instead

of using AI just for code generation, we've developed a true collaborative workflow:

1. AI (LLM) writes initial implementation based on specifications and context

2. Human reviews, runs tests, and commits code with any necessary adjustments

3. Knowledge persists across conversations using Basic Memory's knowledge graph

4. Development continues seamlessly across different AI sessions with consistent context

5. Results improve through iterative collaboration and shared understanding

This approach has allowed us to tackle more complex challenges and build a more robust system than either humans or AI

could achieve independently.

**Problem-Solving Guidance:**

- If a solution isn't working after reasonable effort, suggest alternative approaches

- Don't persist with a problematic library or pattern when better alternatives exist

- Example: When py-pglite caused cascading test failures, switching to testcontainers-postgres was the right call

## GitHub Integration

Basic Memory has taken AI-Human collaboration to the next level by integrating Claude directly into the development workflow through GitHub:

### GitHub MCP Tools

Using the GitHub Model Context Protocol server, Claude can now:

- **Repository Management**:

- View repository files and structure

- Read file contents

- Create new branches

- Create and update files

- **Issue Management**:

- Create new issues

- Comment on existing issues

- Close and update issues

- Search across issues

- **Pull Request Workflow**:

- Create pull requests

- Review code changes

- Add comments to PRs

This integration enables Claude to participate as a full team member in the development process, not just as a code generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic Machines organization with direct contributor access to the codebase.

### Collaborative Development Process

With GitHub integration, the development workflow includes:

1. **Direct code review** - Claude can analyze PRs and provide detailed feedback

2. **Contribution tracking** - All of Claude's contributions are properly attributed in the Git history

3. **Branch management** - Claude can create feature branches for implementations

4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves

5. **Code Commits**: ALWAYS sign off commits with `git commit -s`

6. **Pull Request Titles**: PR titles must follow the semantic format enforced by `.github/workflows/pr-title.yml`: `type(scope): summary`

- Allowed types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`

- Allowed scopes: `core`, `cli`, `api`, `mcp`, `sync`, `ui`, `ci`, `deps`, `installer`, `plugins`, `skills`, `integrations`

- Example: `fix(cli): propagate cloud workspace routing`

This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.