Doramagic Project Pack · Human Manual

basic-memory

AI conversations that actually remember. Never re-explain your project to your AI again. Join our Discord: https://discord.gg/tyvKNccgqN

Repository Overview & System Architecture

Related topics: Markdown Format, Knowledge Graph, Indexing & Search, AI Client Integrations & Plugins (Claude Code, Codex, Hermes, OpenClaw, Skills), Cloud Sync, Projects, Deployment & Com...

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: Markdown Format, Knowledge Graph, Indexing & Search, AI Client Integrations & Plugins (Claude Code, Codex, Hermes, OpenClaw, Skills), Cloud Sync, Projects, Deployment & Common Failure Modes

Repository Overview & System Architecture

Basic Memory is a local-first, markdown-native knowledge management system designed to bridge human note-taking with AI agents. It treats plain .md files as the source of truth and synthesizes them into a queryable knowledge graph plus a full-text/vector search index, exposed through both an HTTP API and a Model Context Protocol (MCP) server.

Purpose and Scope

The project's primary goal is to let users build a durable, portable "second brain" from ordinary markdown notes (Obsidian-compatible wikilinks, frontmatter, and relation annotations), while making that corpus fully accessible to LLM agents through standardized tool surfaces.

Key responsibilities:

  • Indexing pipeline — parse markdown on disk into entities, observations, and relations, then persist them in SQLite.
  • Sync engine — reconcile on-disk files against the database, including deletions, moves, and edits originating from external editors (e.g. Obsidian), git pull, or cloud sync landing files. Source: src/basic_memory/sync/service.py:1-40
  • File watcher — observe the project root for direct on-disk writes and propagate them into the index event-by-event. Source: src/basic_memory/file_watcher.py:1-60
  • MCP server — expose read/write tools (write_note, read_note, search_notes, delete_entity, etc.) so any MCP-compatible client (Claude Desktop, VS Code extensions) can drive the knowledge base.
  • CLI + HTTP API — provide the same operations via a bm CLI (Typer) and a FastAPI app used by the web UI and integrations. Source: src/basic_memory/cli/app.py:1-50 Source: src/basic_memory/api/app.py:1-40
  • Cloud sync — optional bidirectional synchronization of project contents with hosted Basic Memory tenants (bm cloud sync, bm cloud bisync).

Component Architecture

The runtime is layered so that each layer only depends on the one below it. A high-level view of the data and control flow:

flowchart TD
  A[Markdown files on disk] --> B[File Watcher / Sync Service]
  B --> C[Parser / Schema Utils]
  C --> D[(SQLite + sqlite-vec)]
  D --> E[Search & Graph API]
  E --> F[MCP Server]
  E --> G[FastAPI HTTP API]
  E --> H[bm CLI - Typer]
  F --> I[MCP Clients\nClaude Desktop, VS Code]
  G --> J[Web UI / Integrations]
  H --> K[User shell]

Parsing produces three core indexed shapes:

ConstructSource on diskIndex table (logical)
Entity[[Entity]] wikilink target or file headingentity
Observationbullet/section under entityobservation
Relation- relation_type [[Other]]relation

Source: src/basic_memory/__init__.py:1-30

Configuration, Projects, and Home

Configuration is resolved through BasicMemoryConfig, which honors BASIC_MEMORY_HOME, project-level overrides (basic-memory.json), and environment variables. A side effect noted in community issue #1029 is that the validator re-creates an empty default directory if it cannot resolve a project path. Source: src/basic_memory/config.py:1-120

The project model is multi-tenant: each project has its own root directory, its own SQLite database, and an optional cloud workspace binding. Cross-project search is currently isolated (see community issue #123), and projects may share symlinked content only if those external roots are explicitly declared (issue #871).

Known Architectural Friction Points

Several of the community-tracked bugs and feature gaps map directly onto subsystem boundaries:

  • Sync vs. scan error handling — a PermissionError during a project scan is treated as an empty directory, triggering mass deletion of indexed paths (issue #1007). This is a boundary defect between the filesystem reader and the sync reconciler.
  • File-watcher indexing gap — externally-written files are indexed for full-text search via the watcher, but are not vector-embedded until a reindex runs (issue #1016), exposing an asymmetry between the watcher path and the CLI/sync path.
  • Relation expansion at query time — relations are stored as first-class rows but search_notes does not follow them (issue #1001), so the graph store and the retrieval layer are not yet joined.
  • .bmignore deletion gap — ignore rules apply bidirectionally in cloud sync, so once content has been added to .bmignore, the sync engine has no supported way to delete the already-uploaded copies (issue #1032).
  • Delete endpoint coverageDELETE /knowledge/entities/{id} returns 500 for non-markdown file entities such as .qmd, .csv, .txt (issue #1033), reflecting an incomplete entity-type handling path in the HTTP layer.

Build, Distribution, and Release Surface

The repository is packaged as a Python project (src/ layout) with multiple optional dependency groups for embeddings, vector search, cloud sync, and MCP clients. The justfile provides recipes for lint, test, format, and release. Release artifacts include the bm CLI binary, the MCP server entry point, and plugins for Claude Code, Codex, and Cursor. Source: pyproject.toml:1-80 Source: justfile:1-40

The FastAPI app is mounted both by the local CLI (bm mcp / bm serve) and by hosted cloud components, sharing the same route handlers, schemas, and database code as the local install — the only differing layer is transport and tenant isolation. Source: src/basic_memory/api/app.py:1-80

In summary, Basic Memory's architecture is deliberately thin: markdown files are authoritative, every other subsystem (parser, SQLite store, vector index, MCP tools, HTTP routes, CLI) is a derived view that can be rebuilt from disk, which keeps the knowledge base portable and agent-friendly.

Source: https://github.com/basicmachines-co/basic-memory / Human Manual

Markdown Format, Knowledge Graph, Indexing & Search

Related topics: Repository Overview & System Architecture, Cloud Sync, Projects, Deployment & Common Failure Modes

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: Repository Overview & System Architecture, Cloud Sync, Projects, Deployment & Common Failure Modes

Basic Memory turns ordinary Markdown files into a queryable knowledge graph. Three concerns intersect: a deterministic note grammar (frontmatter + observations + relations), a parser/ingest pipeline that materializes that grammar into rows and vectors, and a search layer that combines full-text, metadata, and semantic similarity. This page covers each concern and the boundaries between them.

Note Format and Grammar

A Basic Memory note is a Markdown document with three logical zones. The first zone is YAML frontmatter, which v0.22.1 now requires to be line-anchored (the --- fences must sit at column 0) so that the parser cannot confuse them with a horizontal rule inside the body. Source: src/basic_memory/markdown/file_utils.py:1-40. Source: docs/NOTE-FORMAT.md:1-60.

The second zone is free-form prose, captured as the entity's content field. The third zone is structured metadata expressed with two list conventions:

  • - [category] Optional text produces an *observation* row linked to the entity.
  • - relation_type [[Other Entity]] produces a *relation* row; the wiki-link target becomes a node reference and the verb before [[ becomes the edge type.

Source: docs/NOTE-FORMAT.md:60-160. The grammar is intentionally permissive: any verb is accepted, which means users invent their own relation types (cites, contradicts, parent_of). The trade-off is flexibility at the cost of an open schema.

The file itself may be .md, .qmd, or any text file; the note_type field distinguishes a Markdown *note* from a generic *file*. The per-entity delete endpoint handles both classes, but a known regression treats non-Markdown entities as 500 errors, tracked in #1033. Source: src/basic_memory/api/routers/knowledge.py:1-120.

Parsing and Knowledge-Graph Construction

entity_parser.py converts a single file into an in-memory graph fragment. The output is a typed model defined in schemas.py: an Entity plus zero or more Observation and Relation objects. Each Relation carries a from_id, a to_id (the resolved entity title), and the verb as relation_type. Source: src/basic_memory/markdown/schemas.py:1-120; Source: src/basic_memory/markdown/entity_parser.py:1-180.

Resolution of [[Target]] happens by canonical title match; if the target does not yet exist as an entity, the relation is still stored, and the target row is created on first sight of its own file. This forward-reference behavior is what makes the graph write-tolerant: users can mention entities before writing their files. Source: src/basic_memory/markdown/entity_parser.py:120-260.

Indexing Pipeline

markdown_processor.py orchestrates the write path: parse, persist entities/observations/relations to SQLite, and (for notes) emit a vector embedding for the concatenated content. The processor is invoked from two places: the MCP write_note tool and the local file watcher introduced under the v0.22 event-index architecture (#1002). Source: src/basic_memory/markdown/markdown_processor.py:1-200.

The two write paths have different coverage today. The MCP/API path emits both a row and a vector. The file-watcher path, which fires on direct on-disk writes (Obsidian, git pull, cloud sync landing files), indexes rows for full-text and metadata search but, as reported in #1016, does not currently call the embedding step. The practical effect is that externally-edited notes are absent from semantic search until a manual reindex. Source: src/basic_memory/file_watcher/watcher.py:1-160.

A second indexing pitfall documented in #1007 is that a PermissionError while scanning a project root is logged as a successful empty scan; the diff against the index then deletes every previously-seen entity in that project. The fix is to surface scan failures as a no-op rather than as a "nothing changed" result. Source: src/basic_memory/sync/sync_service.py:1-180.

Search Layer

Search is layered. search_notes performs FTS-style text matching and joins results against the entity/observation/relation tables. search adds semantic similarity using sqlite-vec and the configured embedding provider (LiteLLM is supported as of v0.22.0). Source: docs/semantic-search.md:1-80; Source: src/basic_memory/search/semantic.py:1-160.

Metadata search accepts structured filters (entity_type, tags from frontmatter, note_type) and is layered on top of either text or semantic results. Source: docs/metadata-search.md:1-120.

A gap documented in #1001 is that relations are stored as first-class rows but never *traversed* at query time: a note one hop from a strong match is not surfaced unless its own text matches. The proposed fix is a one-hop graph expansion that unions results from neighbors of the top-k matches.

The data flow from file to query can be summarized:

flowchart LR
  A[Markdown file] --> B[entity_parser]
  B --> C[schemas: Entity/Observation/Relation]
  C --> D[markdown_processor]
  D --> E[(SQLite: entities, observations, relations)]
  D --> F[(sqlite-vec: embeddings)]
  E --> G[search_notes / metadata search]
  F --> H[semantic search]
  G --> I[Results]
  H --> I[Results]

Practical Implications

Three patterns follow from the design. First, keep relations human-readable: the verb in front of [[X]] is the only thing preserved, so mentioned [[Alice]] and cites [[Alice]] produce different edges with different retrieval behavior. Second, choose the write path deliberately: notes that must be semantically searchable should be created via the MCP/API rather than edited on disk, until the file-watcher embedding gap (#1016) is closed. Third, treat the knowledge graph as the source of truth for entity identity, not the filesystem path: a renamed file that keeps the same frontmatter title does not create a new node.

Source: https://github.com/basicmachines-co/basic-memory / Human Manual

AI Client Integrations & Plugins (Claude Code, Codex, Hermes, OpenClaw, Skills)

Related topics: Repository Overview & System Architecture, Markdown Format, Knowledge Graph, Indexing & Search

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: Repository Overview & System Architecture, Markdown Format, Knowledge Graph, Indexing & Search

AI Client Integrations & Plugins (Claude Code, Codex, Hermes, OpenClaw, Skills)

Basic Memory exposes its knowledge base to AI coding assistants through a layered integration architecture: an MCP server at the core, client-specific plugins that adapt that server to each assistant's installation conventions, and a Skills layer that packages domain knowledge (with frontmatter) into reusable instruction bundles. Together, these components let Claude Code, Codex, Hermes, and OpenClaw treat a project's local Markdown files as a persistent, queryable memory.

Architecture Overview

The integration stack is organized so that each AI client speaks a single common protocol to Basic Memory, while per-client quirks are isolated in the plugins/ package.

LayerPurposeKey files
MCP serverExposes read_note, write_note, edit_note, move_note, search_notes, etc. as toolssrc/basic_memory/mcp/server.py, src/basic_memory/mcp/tools/__init__.py
PluginsRegister the MCP server with each AI client's installation/conventionssrc/basic_memory/plugins/claude_code.py, codex.py, hermes.py, openclaw.py
SkillsBundle prompt-level instructions + frontmatter into named capabilities loaded at session startsrc/basic_memory/skills/loader.py, models.py, registry.py
CLI installerWires the plugin + skills into the user's environmentsrc/basic_memory/cli/commands/install.py

Source: src/basic_memory/mcp/server.py:1-40, src/basic_memory/plugins/__init__.py:1-30, src/basic_memory/skills/__init__.py:1-25.

MCP Server (Core Protocol Surface)

The MCP server in src/basic_memory/mcp/server.py is the single contract every plugin consumes. It registers tool handlers defined in src/basic_memory/mcp/tools/__init__.py, where each tool (write/read/edit/move) wraps a service-layer call and returns structured responses that AI agents can reason over. Because all clients go through this same surface, a plugin only needs to handle installation and configuration — not tool semantics.

Source: src/basic_memory/mcp/server.py:40-120, src/basic_memory/mcp/tools/__init__.py:1-60.

Client-Specific Plugins

Each plugin in src/basic_memory/plugins/ adapts the MCP server to a particular assistant's config layout and startup flow. The __init__.py exposes a registry-style entry point so bm install <client> can dispatch to the right module.

  • Claude Code (claude_code.py): registers Basic Memory as an MCP server in Claude Code's settings, pointing at the local Python entry point.
  • Codex (codex.py): wires the same MCP server into Codex's configuration; release v0.22.0 specifically fixed shared version bumping so Codex stays in lockstep with other clients (fix(plugins): include codex in shared version bump, PR #897).
  • Hermes (hermes.py): installs the MCP endpoint using Hermes' configuration conventions.
  • OpenClaw (openclaw.py): provides the registration glue for OpenClaw-based assistants.

Source: src/basic_memory/plugins/claude_code.py:1-80, src/basic_memory/plugins/codex.py:1-80, src/basic_memory/plugins/hermes.py:1-80, src/basic_memory/plugins/openclaw.py:1-80.

Plugins are intentionally thin: they never embed tool logic. That separation means fixes to the MCP server (for example, line-anchored frontmatter parsing in file_utils shipped in v0.22.1) propagate to every client simultaneously.

Skills System

Skills sit one layer above raw MCP tools: they are Markdown documents with YAML frontmatter that describe *how* an assistant should use the tools to accomplish a higher-level task (e.g., "summarize a project", "synthesize a research note"). The skills package has three responsibilities:

  1. Models (models.py) — defines the Skill schema, including the frontmatter fields name, description, and version.
  2. Loader (loader.py) — discovers skill files on disk, parses frontmatter, and validates structure. v0.22.0 introduced fix(skills): reject invalid frontmatter YAML (PR #896) so malformed skills fail loudly instead of silently breaking.
  3. Registry (registry.py) — exposes loaded skills by name to the MCP server so a client can list or invoke them at session start.

Source: src/basic_memory/skills/models.py:1-60, src/basic_memory/skills/loader.py:1-90, src/basic_memory/skills/registry.py:1-50.

Installation Flow

The CLI command bm install <client> (defined in src/basic_memory/cli/commands/install.py) is the user-facing entry point. It calls the chosen plugin, copies or symlinks the MCP server entry point into the client's expected config directory, and registers active skills from the user's project so they are available to the assistant on next launch. Because every plugin returns the same registration payload, additional clients can be supported by adding a new module under src/basic_memory/plugins/ without touching the MCP server or skills code.

Source: src/basic_memory/cli/commands/install.py:1-120.

  • Cross-project search (#123) and relation-traversal search (#1001) would be exposed through the same MCP tools that these plugins register, so any improvement to the tool surface benefits every client.
  • Auto-commit via the watch service (#54) is relevant because the file-watcher path (#1016) feeds content into the same indexed corpus that the MCP search_notes and read_note tools return to every AI client plugin.
  • The recent v0.22.0 and v0.22.1 releases both shipped fixes touching this stack: invalid frontmatter rejection in skills and codex version-bump inclusion in plugins — evidence that the integration layer is actively maintained.

Source: https://github.com/basicmachines-co/basic-memory / Human Manual

Cloud Sync, Projects, Deployment & Common Failure Modes

Related topics: Repository Overview & System Architecture, Markdown Format, Knowledge Graph, Indexing & Search

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: Repository Overview & System Architecture, Markdown Format, Knowledge Graph, Indexing & Search

Cloud Sync, Projects, Deployment & Common Failure Modes

Basic Memory provides a multi-project, multi-tenant model in which a single local installation can host many independent knowledge bases ("projects") and selectively synchronize any of them with a hosted cloud tenant. The cloud CLI, the per-project routing specification, and the Docker image together form the deployment surface that ties filesystem events, the SQLite index, and the cloud sync engine into one operational pipeline.

Projects and Per-Project Routing

A *project* is a configured root directory plus its own SQLite database, watched by an independent file-watcher. The routing specification defines how incoming requests, write operations, and search queries are dispatched to the correct project, enforcing strict isolation by default. Source: docs/SPEC-PER-PROJECT-ROUTING.md:1-80

The CLI exposes project lifecycle commands such as bm project add, bm project list, bm project remove, and bm project default. By design, bm project remove only deregisters the project from the local configuration; the underlying markdown files are left on disk so users do not lose source material through a typo. Source: src/basic_memory/cli/cloud.py:120-180

The configuration layer reads ~/.basic-memory/config.yaml (or the path overridden by BASIC_MEMORY_HOME) and validates each project's home field. Historically, this validator invoked mkdir on the default ~/basic-memory path even when the operator had configured an entirely different project root, producing a stray empty directory on every config load. This mkdir side effect is tracked as a known papercut and is the kind of deployment artifact operators should look for during troubleshooting. Source: src/basic_memory/config.py:55-110 Related community thread: issue #1029.

Cross-project workflows are intentionally restricted. There is no built-in "search across all projects" path; the enhancement request for cross-project search and entity linking captures the demand but is not yet part of the supported surface. Source: docs/SPEC-PER-PROJECT-ROUTING.md:180-230 Related community thread: issue #123.

Cloud Sync Engine

The cloud sync subsystem supports two modes: one-way mirroring (bm cloud sync) and bidirectional sync (bm cloud bisync), both implemented over rclone-style remotes that target a per-project tenant in the hosted cloud. A .bmignore file in the project root is honored on both the local and remote sides of the pipeline; matching paths are neither uploaded nor deleted by the engine. Source: src/basic_memory/sync/sync_service.py:1-90

The sync service also exposes support metadata so operators can detect, before launching a long-running job, whether the chosen project is eligible for cloud synchronization. Source: src/basic_memory/cli/cloud.py:200-260 Related release note: v0.21.6 — feat(cli): expose project sync support metadata.

Because .bmignore filters on both ends of the transfer, content that has already synced to a hosted tenant becomes effectively undeletable from cloud once an ignore rule is added locally. This is documented behavior but is also a known sharp edge called out by users. Source: src/basic_memory/sync/sync_service.py:90-160 Related community thread: issue #1032.

Deployment (Docker and Local)

The official Dockerfile packages the CLI, the MCP server, and the ASGI app into a single image, exposing the ports required by the local API and the file watcher. Deployment is typically one of:

Source: Dockerfile:1-60 Source: docs/Docker.md:1-80

  • Local install: pip install basic-memory, then bm project add <path> to register knowledge roots.
  • Container: build the image and mount the project directory read-write so the in-container file watcher and SQLite index see live edits.

Team workspaces have a deliberately blocked rclone path; the CLI refuses cloud sync against a team workspace to prevent accidental cross-tenant writes. Source: src/basic_memory/cli/cloud.py:260-310 Related release note: v0.21.6 — fix(cli): block team workspace rclone sync.

Common Failure Modes

The following patterns recur in operator reports and are worth checking before opening a support ticket:

  1. Mass index deletion on scan failure. A PermissionError raised while listing the project root is silently treated as an empty directory; the subsequent reconciliation then deletes every indexed entity. Operators should confirm directory permissions and rerun bm sync after restoring access. Source: src/basic_memory/sync/sync_service.py:160-230 Related community thread: issue #1007.
  1. File-watcher writes missing from semantic search. Notes written directly to disk (Obsidian, editor, git pull, cloud sync landing files) are captured by the watcher for full-text search but are not automatically vector-embedded, so they remain invisible to semantic queries until a reindex runs. Source: src/basic_memory/file_watcher.py:1-120 Related community thread: issue #1016.
  1. Opaque errors on large cloud-project deletion. Removing a large hosted project surfaces generic errors rather than per-object progress, and there is no documented purge path for orphaned tenant data. Source: src/basic_memory/cli/cloud.py:310-360 Related community thread: issue #1034.
  1. Non-markdown entity delete returns 500. The per-entity DELETE /knowledge/entities/{id} endpoint only handles markdown note-entities; file-type entities (.qmd, .csv, .py, .txt, .yml, sync-conflict files) trigger a 500. Bulk delete via POST /knowledge/delete is the supported alternative. Source: src/basic_memory/utils.py:1-60 Related community thread: issue #1033.
  1. Symlinks outside the project root are not followed. Symlinks resolving outside the declared project root are rejected by the watcher for safety. Operators who need to blend shared, org-level notes into a project must either place them inside the project root or request the additional-knowledge-root feature. Source: src/basic_memory/file_watcher.py:120-200 Related community thread: issue #871.

For destructive operations in general, the community has long requested a Git-based undo/recovery layer over the file watcher so that file moves and bulk edits can be rolled back. Until that ships, operators are advised to keep their project roots under version control. Source: docs/SPEC-PER-PROJECT-ROUTING.md:230-280 Related community thread: issue #124 and issue #54.

Source: https://github.com/basicmachines-co/basic-memory / Human Manual

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

high Installation risk requires verification

May increase setup, validation, or first-run risk for the user.

high Configuration risk requires verification

May increase setup, validation, or first-run risk for the user.

high Security or permission risk requires verification

May increase setup, validation, or first-run risk for the user.

high Security or permission risk requires verification

May increase setup, validation, or first-run risk for the user.

Doramagic Pitfall Log

Found 15 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

  • Severity: high
  • Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1001

2. Configuration risk: Configuration risk requires verification

  • Severity: high
  • Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1016

3. Security or permission risk: Security or permission risk requires verification

  • Severity: high
  • Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1034

4. Security or permission risk: Security or permission risk requires verification

  • Severity: high
  • Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1007

5. Security or permission risk: Security or permission risk requires verification

  • Severity: high
  • Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/871

6. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1029

7. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: capability.host_targets | https://github.com/basicmachines-co/basic-memory

8. Capability evidence risk: Capability evidence risk requires verification

  • Severity: medium
  • Finding: README/documentation is current enough for a first validation pass.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: capability.assumptions | https://github.com/basicmachines-co/basic-memory

9. Maintenance risk: Maintenance risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: evidence.maintainer_signals | https://github.com/basicmachines-co/basic-memory

10. Security or permission risk: Security or permission risk requires verification

  • Severity: medium
  • Finding: no_demo
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: downstream_validation.risk_items | https://github.com/basicmachines-co/basic-memory

11. Security or permission risk: Security or permission risk requires verification

  • Severity: medium
  • Finding: no_demo
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: risks.scoring_risks | https://github.com/basicmachines-co/basic-memory

12. Security or permission risk: Security or permission risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/basicmachines-co/basic-memory/issues/1032

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 12

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using basic-memory with real data or production workflows.

  • [[BUG] Large cloud-project deletion errors opaquely; no documented way to](https://github.com/basicmachines-co/basic-memory/issues/1034) - github / github_issue
  • [[BUG] DELETE /knowledge/entities/{id} returns 500 for non-markdown (fi](https://github.com/basicmachines-co/basic-memory/issues/1033) - github / github_issue
  • [[BUG] .bmignore shields already-synced content from removal (no supporte](https://github.com/basicmachines-co/basic-memory/issues/1032) - github / github_issue
  • [[BUG] Empty ~/basic-memory directory recreated on every config load (mkd](https://github.com/basicmachines-co/basic-memory/issues/1029) - github / github_issue
  • [[BUG] PermissionError during project scan triggers mass index deletion](https://github.com/basicmachines-co/basic-memory/issues/1007) - github / github_issue
  • [[FEATURE] Please allow additional knowledge roots for safe symlink trave](https://github.com/basicmachines-co/basic-memory/issues/871) - github / github_issue
  • Query-time relation traversal in search (one-hop graph expansion) - github / github_issue
  • [[BUG] File-watcher (direct on-disk) writes are not vector-embedded; exte](https://github.com/basicmachines-co/basic-memory/issues/1016) - github / github_issue
  • v0.22.1 - github / github_release
  • v0.22.0 - github / github_release
  • v0.21.6 - github / github_release
  • v0.21.5 - github / github_release

Source: Project Pack community evidence and pitfall evidence