From 7c787a413cde924a341befa1cd19f031b4613270 Mon Sep 17 00:00:00 2001 From: phernandez Date: Sat, 15 Mar 2025 11:31:18 -0500 Subject: [PATCH] Simpify README.md, ONTRIBUTING.md Signed-off-by: phernandez --- CONTRIBUTING.md | 72 ++++++------ README.md | 293 ++---------------------------------------------- 2 files changed, 48 insertions(+), 317 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cfb4a31d..0402cec0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,7 @@ # Contributing to Basic Memory -Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the project and how to get started as a developer. +Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the +project and how to get started as a developer. ## Getting Started @@ -65,61 +66,64 @@ Thank you for considering contributing to Basic Memory! This document outlines t This project is designed for collaborative development between humans and LLMs (Large Language Models): -1. **CLAUDE.md**: The repository includes a `CLAUDE.md` file that serves as a project guide for both humans and LLMs. This file contains: - - Key project information and architectural overview - - Development commands and workflows - - Code style guidelines - - Documentation standards +1. **CLAUDE.md**: The repository includes a `CLAUDE.md` file that serves as a project guide for both humans and LLMs. + This file contains: + - Key project information and architectural overview + - Development commands and workflows + - Code style guidelines + - Documentation standards 2. **AI-Human Collaborative Workflow**: - - We encourage using LLMs like Claude for code generation, reviews, and documentation - - When possible, save context in markdown files that can be referenced later - - This enables seamless knowledge transfer between different development sessions - - Claude can help with implementation details while you focus on architecture and design + - We encourage using LLMs like Claude for code generation, reviews, and documentation + - When possible, save context in markdown files that can be referenced later + - This enables seamless knowledge transfer between different development sessions + - Claude can help with implementation details while you focus on architecture and design 3. **Adding to CLAUDE.md**: - - If you discover useful project information or common commands, consider adding them to CLAUDE.md - - This helps all contributors (human and AI) maintain consistent knowledge of the project + - If you discover useful project information or common commands, consider adding them to CLAUDE.md + - This helps all contributors (human and AI) maintain consistent knowledge of the project ## Pull Request Process 1. **Create a Pull Request**: Open a PR against the `main` branch with a clear title and description. -2. **Sign the Developer Certificate of Origin (DCO)**: All contributions require signing our DCO, which certifies that you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you create a PR. +2. **Sign the Developer Certificate of Origin (DCO)**: All contributions require signing our DCO, which certifies that + you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you + create a PR. 3. **PR Description**: Include: - - What the PR changes - - Why the change is needed - - How you tested the changes - - Any related issues (use "Fixes #123" to automatically close issues) + - What the PR changes + - Why the change is needed + - How you tested the changes + - Any related issues (use "Fixes #123" to automatically close issues) 4. **Code Review**: Wait for code review and address any feedback. 5. **CI Checks**: Ensure all CI checks pass. 6. **Merge**: Once approved, a maintainer will merge your PR. ## Developer Certificate of Origin -By contributing to this project, you agree to the [Developer Certificate of Origin (DCO)](CLA.md). This means you certify that: +By contributing to this project, you agree to the [Developer Certificate of Origin (DCO)](CLA.md). This means you +certify that: + - You have the right to submit your contributions - You're not knowingly submitting code with patent or copyright issues - Your contributions are provided under the project's license (AGPL-3.0) -This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be properly incorporated into the project and potentially used in commercial applications. +This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be +properly incorporated into the project and potentially used in commercial applications. ### Signing Your Commits -You can sign your commits in one of two ways: +Sign your commit: -1. **Using the `-s` or `--signoff` flag**: - ```bash - git commit -s -m "Your commit message" - ``` - This adds a `Signed-off-by` line to your commit message, certifying that you adhere to the DCO. +**Using the `-s` or `--signoff` flag**: -2. **Configuring Git to automatically sign off**: - ```bash - git config --global alias.cs 'commit -s' - ``` - Then use `git cs -m "Your commit message"` to commit with sign-off. +```bash +git commit -s -m "Your commit message" +``` -The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your agreement to the DCO. +This adds a `Signed-off-by` line to your commit message, certifying that you adhere to the DCO. + +The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your +agreement to the DCO. ## Code Style Guidelines @@ -135,10 +139,10 @@ The sign-off certifies that you have the right to submit your contribution under - **Coverage Target**: We aim for 100% test coverage for all code - **Test Framework**: Use pytest for unit and integration tests -- **Mocking**: Use pytest-mock for mocking dependencies +- **Mocking**: Use pytest-mock for mocking dependencies only when necessary - **Edge Cases**: Test both normal operation and edge cases - **Database Testing**: Use in-memory SQLite for testing database operations -- **Fixtures**: Use pytest fixtures for setup and teardown +- **Fixtures**: Use async pytest fixtures for setup and teardown ## Creating Issues @@ -156,4 +160,4 @@ All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md). ## Thank You! -Your contributions help make Basic Memory better for everyone. We appreciate your time and effort! +Your contributions help make Basic Memory better. We appreciate your time and effort! \ No newline at end of file diff --git a/README.md b/README.md index 87fd210c..79fe4b0c 100644 --- a/README.md +++ b/README.md @@ -68,36 +68,6 @@ Smithery server hosts the MCP server component, while your data remains stored l basic-memory MCP server -### CLI Tools - -You can also install the CLI tools to sync files or manage projects. - -```bash -uv tool install basic-memory - -# create a new project in a different directory -uv tool run basic-memory project add coffee ./examples/coffee - -# you can set the project to the default -uv tool run basic-memory project default coffee -``` - -View available projects - -```bash -basic-memory project list - Basic Memory Projects -┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓ -┃ Name ┃ Path ┃ Default ┃ Active ┃ -┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩ -│ main │ ~/basic-memory │ ✓ │ ✓ │ -│ coffee │ ~/dev/basicmachines/basic-memory/examples/coffee │ │ │ -└────────┴──────────────────────────────────────────────────┴─────────┴────────┘ -``` - -Basic Memory will write notes in Markdown format. Open your project directory in your text editor to view project files -while you have conversations with an LLM. - ## Why Basic Memory? Most LLM interactions are ephemeral - you ask a question, get an answer, and everything is forgotten. Each conversation @@ -454,263 +424,20 @@ canvas(nodes, edges, title, folder) - Generate knowledge visualizations "What have I been working on in the past week?" ``` -## Multiple Projects +## Futher info -Basic Memory supports managing multiple separate knowledge bases through projects. This feature allows you to maintain -separate knowledge graphs for different purposes (e.g., personal notes, work projects, research topics). +See the [Documentation](https://memory.basicmachines.co/) for more info, including: -### Managing Projects - -```bash -# List all configured projects -basic-memory project list - -# Add a new project -basic-memory project add work ~/work-basic-memory - -# Set the default project -basic-memory project default work - -# Remove a project (doesn't delete files) -basic-memory project remove personal - -# Show current project -basic-memory project current -``` - -### Using Projects in Commands - -All commands support the `--project` flag to specify which project to use: - -```bash -# Sync a specific project -basic-memory --project=work sync - -# Run MCP server for a specific project -basic-memory --project=personal mcp -``` - -You can also set the `BASIC_MEMORY_PROJECT` environment variable: - -```bash -BASIC_MEMORY_PROJECT=work basic-memory sync -``` - -### Project Isolation - -Each project maintains: - -- Its own collection of markdown files in the specified directory -- A separate SQLite database for that project -- Complete knowledge graph isolation from other projects - -## Design Philosophy - -Basic Memory is built on some key ideas: - -- Your knowledge should stay in files you control -- Both humans and AI should use natural formats -- Simple text patterns can capture rich meaning -- Local-first doesn't mean feature-poor -- Knowledge should persist across conversations -- AI assistants should build on past context -- File formats should be human-readable and editable -- Semantic structure should emerge from natural patterns -- Knowledge graphs should be both AI and human navigable -- Systems should augment human memory, not replace it - -## Importing Existing Data - -Basic Memory provides CLI commands to import data from various sources, converting them into the structured Markdown -format: - -### Claude.ai - -First, request an export of your data from your Claude account. The data will be emailed to you in several files, -including -`conversations.json` and `projects.json`. - -Import Claude.ai conversation data - -```bash - basic-memory import claude conversations -``` - -The conversations will be turned into Markdown files and placed in the "conversations" folder by default (this can be -changed with the --folder arg). - -Example: - -```bash -Importing chats from conversations.json...writing to .../basic-memory - Reading chat data... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% -╭────────────────────────────╮ -│ Import complete! │ -│ │ -│ Imported 307 conversations │ -│ Containing 7769 messages │ -╰────────────────────────────╯ -``` - -Next, you can run the `sync` command to import the data into basic-memory - -```bash -basic-memory sync -``` - -You can also import project data from Claude.ai - -```bash -➜ basic-memory import claude projects -Importing projects from projects.json...writing to .../basic-memory/projects - Reading project data... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% -╭────────────────────────────────╮ -│ Import complete! │ -│ │ -│ Imported 101 project documents │ -│ Imported 32 prompt templates │ -╰────────────────────────────────╯ - -Run 'basic-memory sync' to index the new files. -``` - -### OpenAI ChatGPT - -```bash - ➜ basic-memory import chatgpt -Importing chats from conversations.json...writing to .../basic-memory/conversations - - Reading chat data... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% -╭────────────────────────────╮ -│ Import complete! │ -│ │ -│ Imported 198 conversations │ -│ Containing 11777 messages │ -╰────────────────────────────╯ - - -``` - -### Knowledge Graph Memory Server - -From the MCP Server: https://github.com/modelcontextprotocol/servers/tree/main/src/memory - -```bash -➜ basic-memory import memory-json -Importing from memory.json...writing to .../basic-memory - Reading memory.json... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% - Creating entities... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% -╭──────────────────────╮ -│ Import complete! │ -│ │ -│ Created 126 entities │ -│ Added 252 relations │ -╰──────────────────────╯ -``` - -## Working with Your Knowledge Base - -Once you've built up a knowledge base, you can interact with it in several ways: - -### Command Line Interface - -Basic Memory provides a powerful CLI for managing your knowledge: - -```bash -# See all available commands -basic-memory --help - -# Check the status of your knowledge sync -basic-memory status - -# Access specific tool functionality directly -basic-memory tools - -# Start a continuous sync process -basic-memory sync --watch -``` - -### Obsidian Integration - -Basic Memory works seamlessly with [Obsidian](https://obsidian.md/), a popular knowledge management app: - -1. Point Obsidian to your Basic Memory directory -2. Use standard Obsidian features like backlinks and graph view -3. See your knowledge graph visually -4. Use the canvas visualization generated by Basic Memory - -### File Organization - -Basic Memory is flexible about how you organize your files: - -- Group by topic in folders -- Use a flat structure with descriptive filenames -- Add custom metadata in frontmatter -- Tag files for better searchability - -The system will build the semantic knowledge graph regardless of your file organization preference. - -## Using stdin with Basic Memory's `write_note` Tool - -The `write-note` tool supports reading content from standard input (stdin), allowing for more flexible workflows when -creating or updating notes in your Basic Memory knowledge base. - -### Use Cases - -This feature is particularly useful for: - -1. **Piping output from other commands** directly into Basic Memory notes -2. **Creating notes with multi-line content** without having to escape quotes or special characters -3. **Integrating with AI assistants** like Claude Code that can generate content and pipe it to Basic Memory -4. **Processing text data** from files or other sources - -## Basic Usage - -### Method 1: Using a Pipe - -You can pipe content from another command into `write_note`: - -```bash -# Pipe output of a command into a new note -echo "# My Note\n\nThis is a test note" | basic-memory tools write-note --title "Test Note" --folder "notes" - -# Pipe output of a file into a new note -cat README.md | basic-memory tools write-note --title "Project README" --folder "documentation" - -# Process text through other tools before saving as a note -cat data.txt | grep "important" | basic-memory tools write-note --title "Important Data" --folder "data" -``` - -### Method 2: Using Heredoc Syntax - -For multi-line content, you can use heredoc syntax: - -```bash -# Create a note with heredoc -cat << EOF | basic-memory tools write_note --title "Project Ideas" --folder "projects" -# Project Ideas for Q2 - -## AI Integration -- Improve recommendation engine -- Add semantic search to product catalog - -## Infrastructure -- Migrate to Kubernetes -- Implement CI/CD pipeline -EOF -``` - -### Method 3: Input Redirection - -You can redirect input from a file: - -```bash -# Create a note from file content -basic-memory tools write-note --title "Meeting Notes" --folder "meetings" < meeting_notes.md -``` +- [Complete User Guide](https://memory.basicmachines.co/docs/user-guide) +- [CLI tools](https://memory.basicmachines.co/docs/cli-reference) +- [Managing multiple Projects](https://memory.basicmachines.co/docs/cli-reference#project) +- [Importing data from OpenAI/Claude Projects](https://memory.basicmachines.co/docs/cli-reference#import) ## License AGPL-3.0 -Built with ♥️ by Basic Machines +Contributions are welcome. See the [Contributing](CONTRIBUTING.md) guide for info about setting up the project locally +and submitting PRs. + +Built with ♥️ by Basic Machines \ No newline at end of file