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...
Continue reading this section for the full explanation and source context.
Related Pages
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
bmCLI (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:
| Construct | Source on disk | Index table (logical) |
|---|---|---|
| Entity | [[Entity]] wikilink target or file heading | entity |
| Observation | bullet/section under entity | observation |
| 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
PermissionErrorduring 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_notesdoes not follow them (issue #1001), so the graph store and the retrieval layer are not yet joined. .bmignoredeletion 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 coverage —
DELETE /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
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Repository Overview & System Architecture, Cloud Sync, Projects, Deployment & Common Failure Modes
Markdown Format, Knowledge Graph, Indexing & Search
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 textproduces 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
Continue reading this section for the full explanation and source context.
Related Pages
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.
| Layer | Purpose | Key files |
|---|---|---|
| MCP server | Exposes read_note, write_note, edit_note, move_note, search_notes, etc. as tools | src/basic_memory/mcp/server.py, src/basic_memory/mcp/tools/__init__.py |
| Plugins | Register the MCP server with each AI client's installation/conventions | src/basic_memory/plugins/claude_code.py, codex.py, hermes.py, openclaw.py |
| Skills | Bundle prompt-level instructions + frontmatter into named capabilities loaded at session start | src/basic_memory/skills/loader.py, models.py, registry.py |
| CLI installer | Wires the plugin + skills into the user's environment | src/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:
- Models (
models.py) — defines theSkillschema, including the frontmatter fields name, description, and version. - Loader (
loader.py) — discovers skill files on disk, parses frontmatter, and validates structure. v0.22.0 introducedfix(skills): reject invalid frontmatter YAML(PR #896) so malformed skills fail loudly instead of silently breaking. - 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.
Related Community Discussions
- 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_notesandread_notetools 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
Continue reading this section for the full explanation and source context.
Related Pages
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, thenbm 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:
- Mass index deletion on scan failure. A
PermissionErrorraised 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 rerunbm syncafter restoring access.Source: src/basic_memory/sync/sync_service.py:160-230Related community thread: issue #1007.
- 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-120Related community thread: issue #1016.
- 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-360Related community thread: issue #1034.
- 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 viaPOST /knowledge/deleteis the supported alternative.Source: src/basic_memory/utils.py:1-60Related community thread: issue #1033.
- 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-200Related 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.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
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.
Count of project-level external discussion links exposed on this manual page.
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