{"id":25826894,"url":"https://github.com/basicmachines-co/basic-memory","last_synced_at":"2026-02-12T23:06:21.101Z","repository":{"id":275677938,"uuid":"897595329","full_name":"basicmachines-co/basic-memory","owner":"basicmachines-co","description":"Basic Memory is a knowledge management system that allows you to build a persistent semantic graph from conversations with AI assistants. All knowledge is stored in standard Markdown files on your computer, giving you full control and ownership of your data. Integrates directly with Obsidan.md","archived":false,"fork":false,"pushed_at":"2025-04-08T16:27:43.000Z","size":33494,"stargazers_count":481,"open_issues_count":15,"forks_count":36,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-13T09:07:27.141Z","etag":null,"topics":["ai","claude","llm","mcp","obsidian","obsidian-md","open-source","python"],"latest_commit_sha":null,"homepage":"https://basicmachines.co","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basicmachines-co.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-02T22:40:43.000Z","updated_at":"2025-04-13T09:04:28.000Z","dependencies_parsed_at":"2025-02-28T03:35:30.116Z","dependency_job_id":"6e7aea3c-16e0-40f2-a371-8997e8a05cd5","html_url":"https://github.com/basicmachines-co/basic-memory","commit_stats":null,"previous_names":["basicmachines-co/basic-memory"],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basicmachines-co","download_url":"https://codeload.github.com/basicmachines-co/basic-memory/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254264771,"owners_count":22041794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","llm","mcp","obsidian","obsidian-md","open-source","python"],"created_at":"2025-02-28T15:45:30.435Z","updated_at":"2026-02-12T23:06:21.081Z","avatar_url":"https://github.com/basicmachines-co.png","language":"Python","readme":"\u003c!-- mcp-name: io.github.basicmachines-co/basic-memory --\u003e\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![PyPI version](https://badge.fury.io/py/basic-memory.svg)](https://badge.fury.io/py/basic-memory)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![Tests](https://github.com/basicmachines-co/basic-memory/workflows/Tests/badge.svg)](https://github.com/basicmachines-co/basic-memory/actions)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n![](https://badge.mcpx.dev?type=server 'MCP Server')\n![](https://badge.mcpx.dev?type=dev 'MCP Dev')\n\n## 🚀 Basic Memory Cloud is Live!\n\n- **Cross-device and multi-platform support is here.** Your knowledge graph now works on desktop, web, and mobile - seamlessly synced across all your AI tools (Claude, ChatGPT, Gemini, Claude Code, and Codex) \n- **Early Supporter Pricing:** Early users get 25% off forever. \nThe open source project continues as always. Cloud just makes it work everywhere.\n\n[Sign up now →](https://basicmemory.com)\n\nwith a 7 day free trial\n\n# Basic Memory\n\nBasic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like\nClaude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to\nenable any compatible LLM to read and write to your local knowledge base.\n\n- Website: https://basicmemory.com\n- Documentation: https://docs.basicmemory.com\n\n## Pick up your conversation right where you left off\n\n- AI assistants can load context from local files in a new conversation\n- Notes are saved locally as Markdown files in real time\n- No project knowledge or special prompting required\n\nhttps://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc\n\n## Quick Start\n\n```bash\n# Install with uv (recommended)\nuv tool install basic-memory\n\n# Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)\n# Add this to your config:\n{\n  \"mcpServers\": {\n    \"basic-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"basic-memory\",\n        \"mcp\"\n      ]\n    }\n  }\n}\n# Now in Claude Desktop, you can:\n# - Write notes with \"Create a note about coffee brewing methods\"\n# - Read notes with \"What do I know about pour over coffee?\"\n# - Search with \"Find information about Ethiopian beans\"\n\n```\n\nYou can view shared context via files in `~/basic-memory` (default directory location).\n\n## Why Basic Memory?\n\nMost LLM interactions are ephemeral - you ask a question, get an answer, and everything is forgotten. Each conversation\nstarts fresh, without the context or knowledge from previous ones. Current workarounds have limitations:\n\n- Chat histories capture conversations but aren't structured knowledge\n- RAG systems can query documents but don't let LLMs write back\n- Vector databases require complex setups and often live in the cloud\n- Knowledge graphs typically need specialized tools to maintain\n\nBasic Memory addresses these problems with a simple approach: structured Markdown files that both humans and LLMs can\nread\nand write to. The key advantages:\n\n- **Local-first:** All knowledge stays in files you control\n- **Bi-directional:** Both you and the LLM read and write to the same files\n- **Structured yet simple:** Uses familiar Markdown with semantic patterns\n- **Traversable knowledge graph:** LLMs can follow links between topics\n- **Standard formats:** Works with existing editors like Obsidian\n- **Lightweight infrastructure:** Just local files indexed in a local SQLite database\n\nWith Basic Memory, you can:\n\n- Have conversations that build on previous knowledge\n- Create structured notes during natural conversations\n- Have conversations with LLMs that remember what you've discussed before\n- Navigate your knowledge graph semantically\n- Keep everything local and under your control\n- Use familiar tools like Obsidian to view and edit notes\n- Build a personal knowledge base that grows over time\n- Sync your knowledge to the cloud with bidirectional synchronization\n- Authenticate and manage cloud projects with subscription validation\n- Mount cloud storage for direct file access\n\n## How It Works in Practice\n\nLet's say you're exploring coffee brewing methods and want to capture your knowledge. Here's how it works:\n\n1. Start by chatting normally:\n\n```\nI've been experimenting with different coffee brewing methods. Key things I've learned:\n\n- Pour over gives more clarity in flavor than French press\n- Water temperature is critical - around 205°F seems best\n- Freshly ground beans make a huge difference\n```\n\n... continue conversation.\n\n2. Ask the LLM to help structure this knowledge:\n\n```\n\"Let's write a note about coffee brewing methods.\"\n```\n\nLLM creates a new Markdown file on your system (which you can see instantly in Obsidian or your editor):\n\n```markdown\n---\ntitle: Coffee Brewing Methods\npermalink: coffee-brewing-methods\ntags:\n- coffee\n- brewing\n---\n\n# Coffee Brewing Methods\n\n## Observations\n\n- [method] Pour over provides more clarity and highlights subtle flavors\n- [technique] Water temperature at 205°F (96°C) extracts optimal compounds\n- [principle] Freshly ground beans preserve aromatics and flavor\n\n## Relations\n\n- relates_to [[Coffee Bean Origins]]\n- requires [[Proper Grinding Technique]]\n- affects [[Flavor Extraction]]\n```\n\nThe note embeds semantic content and links to other topics via simple Markdown formatting.\n\n3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).\n\n- Realtime sync can be enabled via running `basic-memory sync --watch`\n\n4. In a chat with the LLM, you can reference a topic:\n\n```\nLook at `coffee-brewing-methods` for context about pour over coffee\n```\n\nThe LLM can now build rich context from the knowledge graph. For example:\n\n```\nFollowing relation 'relates_to [[Coffee Bean Origins]]':\n- Found information about Ethiopian Yirgacheffe\n- Notes on Colombian beans' nutty profile\n- Altitude effects on bean characteristics\n\nFollowing relation 'requires [[Proper Grinding Technique]]':\n- Burr vs. blade grinder comparisons\n- Grind size recommendations for different methods\n- Impact of consistent particle size on extraction\n```\n\nEach related document can lead to more context, building a rich semantic understanding of your knowledge base.\n\nThis creates a two-way flow where:\n\n- Humans write and edit Markdown files\n- LLMs read and write through the MCP protocol\n- Sync keeps everything consistent\n- All knowledge stays in local files.\n\n## Technical Implementation\n\nUnder the hood, Basic Memory:\n\n1. Stores everything in Markdown files\n2. Uses a SQLite database for searching and indexing\n3. Extracts semantic meaning from simple Markdown patterns\n    - Files become `Entity` objects\n    - Each `Entity` can have `Observations`, or facts associated with it\n    - `Relations` connect entities together to form the knowledge graph\n4. Maintains the local knowledge graph derived from the files\n5. Provides bidirectional synchronization between files and the knowledge graph\n6. Implements the Model Context Protocol (MCP) for AI integration\n7. Exposes tools that let AI assistants traverse and manipulate the knowledge graph\n8. Uses memory:// URLs to reference entities across tools and conversations\n\nThe file format is just Markdown with some simple markup:\n\nEach Markdown file has:\n\n### Frontmatter\n\n```markdown\ntitle: \u003cEntity title\u003e\ntype: \u003cThe type of Entity\u003e (e.g. note)\npermalink: \u003ca uri slug\u003e\n\n- \u003coptional metadata\u003e (such as tags) \n```\n\n### Observations\n\nObservations are facts about a topic.\nThey can be added by creating a Markdown list with a special format that can reference a `category`, `tags` using a\n\"#\" character, and an optional `context`.\n\nObservation Markdown format:\n\n```markdown\n- [category] content #tag (optional context)\n```\n\nExamples of observations:\n\n```markdown\n- [method] Pour over extracts more floral notes than French press\n- [tip] Grind size should be medium-fine for pour over #brewing\n- [preference] Ethiopian beans have bright, fruity flavors (especially from Yirgacheffe)\n- [fact] Lighter roasts generally contain more caffeine than dark roasts\n- [experiment] Tried 1:15 coffee-to-water ratio with good results\n- [resource] James Hoffman's V60 technique on YouTube is excellent\n- [question] Does water temperature affect extraction of different compounds differently?\n- [note] My favorite local shop uses a 30-second bloom time\n```\n\n### Relations\n\nRelations are links to other topics. They define how entities connect in the knowledge graph.\n\nMarkdown format:\n\n```markdown\n- relation_type [[WikiLink]] (optional context)\n```\n\nExamples of relations:\n\n```markdown\n- pairs_well_with [[Chocolate Desserts]]\n- grown_in [[Ethiopia]]\n- contrasts_with [[Tea Brewing Methods]]\n- requires [[Burr Grinder]]\n- improves_with [[Fresh Beans]]\n- relates_to [[Morning Routine]]\n- inspired_by [[Japanese Coffee Culture]]\n- documented_in [[Coffee Journal]]\n```\n\n## Using with VS Code\n\nAdd the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"basic-memory\": {\n        \"command\": \"uvx\",\n        \"args\": [\"basic-memory\", \"mcp\"]\n      }\n    }\n  }\n}\n```\n\nOptionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.\n\n```json\n{\n  \"servers\": {\n    \"basic-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\"basic-memory\", \"mcp\"]\n    }\n  }\n}\n```\n\nYou can use Basic Memory with VS Code to easily retrieve and store information while coding.\n\n## Using with Claude Desktop\n\nBasic Memory is built using the MCP (Model Context Protocol) and works with the Claude desktop app (https://claude.ai/):\n\n1. Configure Claude Desktop to use Basic Memory:\n\nEdit your MCP configuration file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json`\nfor OS X):\n\n```json\n{\n  \"mcpServers\": {\n    \"basic-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"basic-memory\",\n        \"mcp\"\n      ]\n    }\n  }\n}\n```\n\nIf you want to use a specific project (see [Multiple Projects](#multiple-projects) below), update your Claude Desktop\nconfig:\n\n```json\n{\n  \"mcpServers\": {\n    \"basic-memory\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"basic-memory\",\n        \"mcp\",\n        \"--project\",\n        \"your-project-name\"\n      ]\n    }\n  }\n}\n```\n\n2. Sync your knowledge:\n\n```bash\n# One-time sync of local knowledge updates\nbasic-memory sync\n\n# Run realtime sync process (recommended)\nbasic-memory sync --watch\n```\n\n3. Cloud features (optional, requires subscription):\n\n```bash\n# Authenticate with cloud\nbasic-memory cloud login\n\n# Bidirectional sync with cloud\nbasic-memory cloud sync\n\n# Verify cloud integrity\nbasic-memory cloud check\n\n# Mount cloud storage\nbasic-memory cloud mount\n```\n\n**Routing Flags** (for users with cloud subscriptions):\n\nWhen cloud mode is enabled, CLI commands communicate with the cloud API by default. Use routing flags to override this:\n\n```bash\n# Force local routing (useful for local MCP server while cloud mode is enabled)\nbasic-memory status --local\nbasic-memory project list --local\n\n# Force cloud routing (when cloud mode is disabled but you want cloud access)\nbasic-memory status --cloud\nbasic-memory project info my-project --cloud\n```\n\nThe local MCP server (`basic-memory mcp`) automatically uses local routing, so you can use both local Claude Desktop and cloud-based clients simultaneously.\n\n4. In Claude Desktop, the LLM can now use these tools:\n\n**Content Management:**\n```\nwrite_note(title, content, folder, tags) - Create or update notes\nread_note(identifier, page, page_size) - Read notes by title or permalink\nread_content(path) - Read raw file content (text, images, binaries)\nview_note(identifier) - View notes as formatted artifacts\nedit_note(identifier, operation, content) - Edit notes incrementally\nmove_note(identifier, destination_path) - Move notes with database consistency\ndelete_note(identifier) - Delete notes from knowledge base\n```\n\n**Knowledge Graph Navigation:**\n```\nbuild_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs\nrecent_activity(type, depth, timeframe) - Find recently updated information\nlist_directory(dir_name, depth) - Browse directory contents with filtering\n```\n\n**Search \u0026 Discovery:**\n```\nsearch(query, page, page_size) - Search across your knowledge base\nsearch_notes(query, page, page_size, search_type, types, entity_types, after_date, metadata_filters, tags, status, project) - Search with filters\nsearch_by_metadata(filters, limit, offset, project) - Structured frontmatter search\n```\n\n**Project Management:**\n```\nlist_memory_projects() - List all available projects\ncreate_memory_project(project_name, project_path) - Create new projects\nget_current_project() - Show current project stats\nsync_status() - Check synchronization status\n```\n\n**Visualization:**\n```\ncanvas(nodes, edges, title, folder) - Generate knowledge visualizations\n```\n\n5. Example prompts to try:\n\n```\n\"Create a note about our project architecture decisions\"\n\"Find information about JWT authentication in my notes\"\n\"Create a canvas visualization of my project components\"\n\"Read my notes on the authentication system\"\n\"What have I been working on in the past week?\"\n```\n\n## Futher info\n\nSee the [Documentation](https://docs.basicmemory.com) for more info, including:\n\n- [Complete User Guide](https://docs.basicmemory.com/user-guide/)\n- [CLI tools](https://docs.basicmemory.com/guides/cli-reference/)\n- [Cloud CLI and Sync](https://docs.basicmemory.com/guides/cloud-cli/)\n- [Managing multiple Projects](https://docs.basicmemory.com/guides/cli-reference/#project)\n- [Importing data from OpenAI/Claude Projects](https://docs.basicmemory.com/guides/cli-reference/#import)\n\n## Logging\n\nBasic Memory uses [Loguru](https://github.com/Delgan/loguru) for logging. The logging behavior varies by entry point:\n\n| Entry Point | Default Behavior | Use Case |\n|-------------|------------------|----------|\n| CLI commands | File only | Prevents log output from interfering with command output |\n| MCP server | File only | Stdout would corrupt the JSON-RPC protocol |\n| API server | File (local) or stdout (cloud) | Docker/cloud deployments use stdout |\n\n**Log file location:** `~/.basic-memory/basic-memory.log` (10MB rotation, 10 days retention)\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `BASIC_MEMORY_LOG_LEVEL` | `INFO` | Log level: DEBUG, INFO, WARNING, ERROR |\n| `BASIC_MEMORY_CLOUD_MODE` | `false` | When `true`, API logs to stdout with structured context |\n| `BASIC_MEMORY_FORCE_LOCAL` | `false` | When `true`, forces local API routing (ignores cloud mode) |\n| `BASIC_MEMORY_ENV` | `dev` | Set to `test` for test mode (stderr only) |\n\n### Examples\n\n```bash\n# Enable debug logging\nBASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory sync\n\n# View logs\ntail -f ~/.basic-memory/basic-memory.log\n\n# Cloud/Docker mode (stdout logging with structured context)\nBASIC_MEMORY_CLOUD_MODE=true uvicorn basic_memory.api.app:app\n```\n\n## Development\n\n### Running Tests\n\nBasic Memory supports dual database backends (SQLite and Postgres). By default, tests run against SQLite. Set `BASIC_MEMORY_TEST_POSTGRES=1` to run against Postgres (uses testcontainers - Docker required).\n\n**Quick Start:**\n```bash\n# Run all tests against SQLite (default, fast)\njust test-sqlite\n\n# Run all tests against Postgres (uses testcontainers)\njust test-postgres\n\n# Run both SQLite and Postgres tests\njust test\n```\n\n**Available Test Commands:**\n\n- `just test` - Run all tests against both SQLite and Postgres\n- `just test-sqlite` - Run all tests against SQLite (fast, no Docker needed)\n- `just test-postgres` - Run all tests against Postgres (uses testcontainers)\n- `just test-unit-sqlite` - Run unit tests against SQLite\n- `just test-unit-postgres` - Run unit tests against Postgres\n- `just test-int-sqlite` - Run integration tests against SQLite\n- `just test-int-postgres` - Run integration tests against Postgres\n- `just test-windows` - Run Windows-specific tests (auto-skips on other platforms)\n- `just test-benchmark` - Run performance benchmark tests\n- `just testmon` - Run tests impacted by recent changes (pytest-testmon)\n- `just test-smoke` - Run fast MCP end-to-end smoke test\n- `just fast-check` - Run fix/format/typecheck + impacted tests + smoke test\n- `just doctor` - Run local file \u003c-\u003e DB consistency checks with temp config\n\n**Postgres Testing:**\n\nPostgres tests use [testcontainers](https://testcontainers-python.readthedocs.io/) which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.\n\n**Testmon Note:** When no files have changed, `just testmon` may collect 0 tests. That's expected and means no impacted tests were detected.\n\n**Test Markers:**\n\nTests use pytest markers for selective execution:\n- `windows` - Windows-specific database optimizations\n- `benchmark` - Performance tests (excluded from default runs)\n- `smoke` - Fast MCP end-to-end smoke tests\n\n**Other Development Commands:**\n```bash\njust install          # Install with dev dependencies\njust lint             # Run linting checks\njust typecheck        # Run type checking\njust format           # Format code with ruff\njust fast-check       # Fast local loop (fix/format/typecheck + testmon + smoke)\njust doctor           # Local consistency check (temp config)\njust check            # Run all quality checks\njust migration \"msg\"  # Create database migration\n```\n\n**Local Consistency Check:**\n```bash\nbasic-memory doctor   # Verifies file \u003c-\u003e database sync in a temp project\n```\n\nSee the [justfile](justfile) for the complete list of development commands.\n\n## License\n\nAGPL-3.0\n\nContributions are welcome. See the [Contributing](CONTRIBUTING.md) guide for info about setting up the project locally\nand submitting PRs.\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/#basicmachines-co/basic-memory\u0026Date\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=basicmachines-co/basic-memory\u0026type=Date\u0026theme=dark\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=basicmachines-co/basic-memory\u0026type=Date\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=basicmachines-co/basic-memory\u0026type=Date\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\nBuilt with ♥️ by Basic Machines\n","funding_links":[],"categories":["AI Memory \u0026 RAG","HarmonyOS","Ai Integration Mcp Servers","MCP 服务器精选列表","Knowledge \u0026 Memory","ai","📚 Projects (1974 total)","Community Servers","Python","Memory Management","python","Project \u0026 Knowledge Management","📦 Other","Table of Contents","MCP Servers","🗂️ Extensions by Category"],"sub_categories":["Memory","Windows Manager","🧠 知识、记忆与 RAG","How to Submit","MCP Servers","Other IDEs","Knowledge and Memory","Knowledge \u0026 Memory","🧠 Knowledge Base"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasicmachines-co%2Fbasic-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasicmachines-co%2Fbasic-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasicmachines-co%2Fbasic-memory/lists"}