basic-memory 0.0.0__tar.gz → 0.1.0__tar.gz

basic_memory-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.12" ]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e .[dev]
+
+      - name: Run tests
+        run: |
+          uv pip install pytest pytest-cov
+          uv run make test

basic_memory-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# CHANGELOG
+
+
+## v0.1.0 (2025-02-07)
+
+### Bug Fixes
+
+- Create virtual env in test workflow
+  ([`8092e6d`](https://github.com/basicmachines-co/basic-memory/commit/8092e6d38d536bfb6f93c3d21ea9baf1814f9b0a))
+
+- Fix permalink uniqueness violations on create/update/sync
+  ([`135bec1`](https://github.com/basicmachines-co/basic-memory/commit/135bec181d9b3d53725c8af3a0959ebc1aa6afda))
+
+- Fix recent activity bug
+  ([`3d2c0c8`](https://github.com/basicmachines-co/basic-memory/commit/3d2c0c8c32fcfdaf70a1f96a59d8f168f38a1aa9))
+
+- Install fastapi deps after removing basic-foundation
+  ([`51a741e`](https://github.com/basicmachines-co/basic-memory/commit/51a741e7593a1ea0e5eb24e14c70ff61670f9663))
+
+- Remove basic-foundation from deps
+  ([`b8d0c71`](https://github.com/basicmachines-co/basic-memory/commit/b8d0c7160f29c97cdafe398a7e6a5240473e0c89))
+
+- Run tests via uv
+  ([`4eec820`](https://github.com/basicmachines-co/basic-memory/commit/4eec820a32bc059a405e2f4dac4c73b245ca4722))
+
+### Chores
+
+- Rename import tool
+  ([`af6b7dc`](https://github.com/basicmachines-co/basic-memory/commit/af6b7dc40a55eaa2aa78d6ea831e613851081d52))
+
+### Features
+
+- Add memory-json importer, tweak observation content
+  ([`3484e26`](https://github.com/basicmachines-co/basic-memory/commit/3484e26631187f165ee6eb85517e94717b7cf2cf))
+
+
+## v0.0.1 (2025-02-04)
+
+### Bug Fixes
+
+- Fix versioning for 0.0.1 release
+  ([`ba1e494`](https://github.com/basicmachines-co/basic-memory/commit/ba1e494ed1afbb7af3f97c643126bced425da7e0))
+
+
+## v0.0.0 (2025-02-04)
+
+### Chores
+
+- Remove basic-foundation src ref in pyproject.toml
+  ([`29fce8b`](https://github.com/basicmachines-co/basic-memory/commit/29fce8b0b922d54d7799bf2534107ee6cfb961b8))

basic_memory-0.1.0/PKG-INFO

@@ -0,0 +1,296 @@
+Metadata-Version: 2.4
+Name: basic-memory
+Version: 0.1.0
+Summary: Local-first knowledge management combining Zettelkasten with knowledge graphs
+Project-URL: Homepage, https://github.com/basicmachines-co/basic-memory
+Project-URL: Repository, https://github.com/basicmachines-co/basic-memory
+Project-URL: Documentation, https://github.com/basicmachines-co/basic-memory#readme
+Author-email: Basic Machines <hello@basic-machines.co>
+License: AGPL-3.0-or-later
+License-File: LICENSE
+Requires-Python: >=3.12.1
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: alembic>=1.14.1
+Requires-Dist: dateparser>=1.2.0
+Requires-Dist: fastapi[standard]>=0.115.8
+Requires-Dist: greenlet>=3.1.1
+Requires-Dist: icecream>=2.1.3
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: markdown-it-py>=3.0.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pydantic-settings>=2.6.1
+Requires-Dist: pydantic[email,timezone]>=2.10.3
+Requires-Dist: pyright>=1.1.390
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.9.4
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: unidecode>=1.3.8
+Requires-Dist: watchfiles>=1.0.4
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.1.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Basic Memory
+
+Basic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like
+Claude, while keeping everything in simple markdown files on your computer. It uses the Model Context Protocol (MCP) to
+enable any compatible LLM to read and write to your local knowledge base.
+
+## What is Basic Memory?
+
+Most people use LLMs like calculators - paste in some text, expect to get an answer back, repeat. Each conversation
+starts fresh,
+and any knowledge or context is lost. Some try to work around this by:
+
+- Saving chat histories (but they're hard to reference)
+- Copying and pasting previous conversations (messy and repetitive)
+- Using RAG systems to query documents (complex and often cloud-based)
+
+Basic Memory takes a different approach by letting both humans and LLMs read and write knowledge naturally using
+standard markdown files. This means:
+
+- Your knowledge stays in files you control
+- Both you and the LLM can read and write notes
+- Context persists across conversations
+- Context stays local and user controlled
+
+## How It Works in Practice
+
+Let's say you're working on a new project and want to capture design decisions. Here's how it works:
+
+1. Start by chatting normally:
+
+```markdown
+We need to design a new auth system, some key features:
+
+- local first, don't delegate users to third party system
+- support multiple platforms via jwt
+- want to keep it simple but secure
+```
+
+... continue conversation.
+
+2. Ask Claude to help structure this knowledge:
+
+```
+"Lets write a note about the auth system design."
+```
+
+Claude creates a new markdown file on your system (which you can see instantly in Obsidian or your editor):
+
+```markdown
+---
+title: Auth System Design
+permalink: auth-system-design
+tags
+- design
+- auth
+---
+
+# Auth System Design
+
+## Observations
+
+- [requirement] Local-first authentication without third party delegation
+- [tech] JWT-based auth for cross-platform support
+- [principle] Balance simplicity with security
+
+## Relations
+
+- implements [[Security Requirements]]
+- relates_to [[Platform Support]]
+- referenced_by [[JWT Implementation]]
+```
+
+The note embeds semantic content (Observations) and links to other topics (Relations) via simple markdown formatting.
+
+3. You can edit this file directly in your editor in real time:
+
+```markdown
+# Auth System Design
+
+## Observations
+
+- [requirement] Local-first authentication without third party delegation
+- [tech] JWT-based auth for cross-platform support
+- [principle] Balance simplicity with security
+- [decision] Will use bcrypt for password hashing # Added by you
+
+## Relations
+
+- implements [[Security Requirements]]
+- relates_to [[Platform Support]]
+- referenced_by [[JWT Implementation]]
+- blocks [[User Service]]  # Added by you
+```
+
+4. In a new chat with Claude, you can reference this knowledge:
+
+```
+"Claude, look at memory://auth-system-design for context about our auth system"
+```
+
+Claude can now build rich context from the knowledge graph. For example:
+
+```
+Following relation 'implements [[Security Requirements]]':
+- Found authentication best practices
+- OWASP guidelines for JWT
+- Rate limiting requirements
+
+Following relation 'relates_to [[Platform Support]]':
+- Mobile auth requirements 
+- Browser security considerations
+- JWT storage strategies
+```
+
+Each related document can lead to more context, building a rich semantic understanding of your knowledge base. All of
+this context comes from standard markdown files that both humans and LLMs can read and write.
+
+Everything stays in local markdown files that you can:
+
+- Edit in any text editor
+- Version via git
+- Back up normally
+- Share when you want to
+
+## Technical Implementation
+
+Under the hood, Basic Memory:
+
+1. Stores everything in markdown files
+2. Uses a SQLite database just for searching and indexing
+3. Extracts semantic meaning from simple markdown patterns
+4. Maintains a local knowledge graph from file content
+
+The file format is just markdown with some simple markup:
+
+Frontmatter
+
+- title
+- type
+- permalink
+- optional metadata
+
+Observations
+
+- facts about a topic
+
+```markdown
+- [category] content #tag (optional context)
+```
+
+Relations
+
+- links to other topics
+
+```markdown
+- relation_type [[WikiLink]] (optional context)
+```
+
+Example:
+
+```markdown
+---
+title: Note tile
+type: note
+permalink: unique/stable/id  # Added automatically
+tags
+- tag1
+- tag2
+---
+
+# Note Title
+
+Regular markdown content...
+
+## Observations
+
+- [category] Structured knowledge #tag (optional context)
+- [idea] Another observation
+
+## Relations
+
+- links_to [[Other Note]]
+- implements [[Some Spec]]
+```
+
+Basic Memory will parse the markdown and derive the semantic relationships in the content. When you run
+`basic-memory sync`:
+
+1. New and changed files are detected
+2. Markdown patterns become semantic knowledge:
+
+- `[tech]` becomes a categorized observation
+- `[[WikiLink]]` creates a relation in the knowledge graph
+- Tags and metadata are indexed for search
+
+3. A SQLite database maintains these relationships for fast querying
+4. Claude and other MCP-compatible LLMs can access this knowledge via memory:// URLs
+
+This creates a two-way flow where:
+
+- Humans write and edit markdown files
+- LLMs read and write through the MCP protocol
+- Sync keeps everything consistent
+- All knowledge stays in local files.
+
+## Using with Claude
+
+Basic Memory works with the Claude desktop app (https://claude.ai/):
+
+1. Install Basic Memory locally:
+
+```bash
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory"
+      ]
+    }
+}
+```
+
+2. Add to Claude Desktop:
+
+```
+Basic Memory is available with these tools:
+- write_note() for creating/updating notes
+- read_note() for loading notes
+- build_context() to load notes via memory:// URLs
+- recent_activity() to find recently updated information
+- search() to search infomation in the knowledge base
+```
+
+3. Install via uv
+
+```bash
+uv add  basic-memory
+
+# sync local knowledge updates
+basic-memory sync
+
+# run realtime sync process
+basic-memory sync --watch
+```
+
+## 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
+
+## License
+
+AGPL-3.0

basic_memory-0.1.0/README.md

@@ -0,0 +1,258 @@
+# Basic Memory
+
+Basic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like
+Claude, while keeping everything in simple markdown files on your computer. It uses the Model Context Protocol (MCP) to
+enable any compatible LLM to read and write to your local knowledge base.
+
+## What is Basic Memory?
+
+Most people use LLMs like calculators - paste in some text, expect to get an answer back, repeat. Each conversation
+starts fresh,
+and any knowledge or context is lost. Some try to work around this by:
+
+- Saving chat histories (but they're hard to reference)
+- Copying and pasting previous conversations (messy and repetitive)
+- Using RAG systems to query documents (complex and often cloud-based)
+
+Basic Memory takes a different approach by letting both humans and LLMs read and write knowledge naturally using
+standard markdown files. This means:
+
+- Your knowledge stays in files you control
+- Both you and the LLM can read and write notes
+- Context persists across conversations
+- Context stays local and user controlled
+
+## How It Works in Practice
+
+Let's say you're working on a new project and want to capture design decisions. Here's how it works:
+
+1. Start by chatting normally:
+
+```markdown
+We need to design a new auth system, some key features:
+
+- local first, don't delegate users to third party system
+- support multiple platforms via jwt
+- want to keep it simple but secure
+```
+
+... continue conversation.
+
+2. Ask Claude to help structure this knowledge:
+
+```
+"Lets write a note about the auth system design."
+```
+
+Claude creates a new markdown file on your system (which you can see instantly in Obsidian or your editor):
+
+```markdown
+---
+title: Auth System Design
+permalink: auth-system-design
+tags
+- design
+- auth
+---
+
+# Auth System Design
+
+## Observations
+
+- [requirement] Local-first authentication without third party delegation
+- [tech] JWT-based auth for cross-platform support
+- [principle] Balance simplicity with security
+
+## Relations
+
+- implements [[Security Requirements]]
+- relates_to [[Platform Support]]
+- referenced_by [[JWT Implementation]]
+```
+
+The note embeds semantic content (Observations) and links to other topics (Relations) via simple markdown formatting.
+
+3. You can edit this file directly in your editor in real time:
+
+```markdown
+# Auth System Design
+
+## Observations
+
+- [requirement] Local-first authentication without third party delegation
+- [tech] JWT-based auth for cross-platform support
+- [principle] Balance simplicity with security
+- [decision] Will use bcrypt for password hashing # Added by you
+
+## Relations
+
+- implements [[Security Requirements]]
+- relates_to [[Platform Support]]
+- referenced_by [[JWT Implementation]]
+- blocks [[User Service]]  # Added by you
+```
+
+4. In a new chat with Claude, you can reference this knowledge:
+
+```
+"Claude, look at memory://auth-system-design for context about our auth system"
+```
+
+Claude can now build rich context from the knowledge graph. For example:
+
+```
+Following relation 'implements [[Security Requirements]]':
+- Found authentication best practices
+- OWASP guidelines for JWT
+- Rate limiting requirements
+
+Following relation 'relates_to [[Platform Support]]':
+- Mobile auth requirements 
+- Browser security considerations
+- JWT storage strategies
+```
+
+Each related document can lead to more context, building a rich semantic understanding of your knowledge base. All of
+this context comes from standard markdown files that both humans and LLMs can read and write.
+
+Everything stays in local markdown files that you can:
+
+- Edit in any text editor
+- Version via git
+- Back up normally
+- Share when you want to
+
+## Technical Implementation
+
+Under the hood, Basic Memory:
+
+1. Stores everything in markdown files
+2. Uses a SQLite database just for searching and indexing
+3. Extracts semantic meaning from simple markdown patterns
+4. Maintains a local knowledge graph from file content
+
+The file format is just markdown with some simple markup:
+
+Frontmatter
+
+- title
+- type
+- permalink
+- optional metadata
+
+Observations
+
+- facts about a topic
+
+```markdown
+- [category] content #tag (optional context)
+```
+
+Relations
+
+- links to other topics
+
+```markdown
+- relation_type [[WikiLink]] (optional context)
+```
+
+Example:
+
+```markdown
+---
+title: Note tile
+type: note
+permalink: unique/stable/id  # Added automatically
+tags
+- tag1
+- tag2
+---
+
+# Note Title
+
+Regular markdown content...
+
+## Observations
+
+- [category] Structured knowledge #tag (optional context)
+- [idea] Another observation
+
+## Relations
+
+- links_to [[Other Note]]
+- implements [[Some Spec]]
+```
+
+Basic Memory will parse the markdown and derive the semantic relationships in the content. When you run
+`basic-memory sync`:
+
+1. New and changed files are detected
+2. Markdown patterns become semantic knowledge:
+
+- `[tech]` becomes a categorized observation
+- `[[WikiLink]]` creates a relation in the knowledge graph
+- Tags and metadata are indexed for search
+
+3. A SQLite database maintains these relationships for fast querying
+4. Claude and other MCP-compatible LLMs can access this knowledge via memory:// URLs
+
+This creates a two-way flow where:
+
+- Humans write and edit markdown files
+- LLMs read and write through the MCP protocol
+- Sync keeps everything consistent
+- All knowledge stays in local files.
+
+## Using with Claude
+
+Basic Memory works with the Claude desktop app (https://claude.ai/):
+
+1. Install Basic Memory locally:
+
+```bash
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory"
+      ]
+    }
+}
+```
+
+2. Add to Claude Desktop:
+
+```
+Basic Memory is available with these tools:
+- write_note() for creating/updating notes
+- read_note() for loading notes
+- build_context() to load notes via memory:// URLs
+- recent_activity() to find recently updated information
+- search() to search infomation in the knowledge base
+```
+
+3. Install via uv
+
+```bash
+uv add  basic-memory
+
+# sync local knowledge updates
+basic-memory sync
+
+# run realtime sync process
+basic-memory sync --watch
+```
+
+## 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
+
+## License
+
+AGPL-3.0

{basic_memory-0.0.0 → basic_memory-0.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "basic-memory"
-version = "0.0.0"
+version = "0.1.0"
 description = "Local-first knowledge management combining Zettelkasten with knowledge graphs"
 readme = "README.md"
 requires-python = ">=3.12.1"
@@ -20,13 +20,14 @@ dependencies = [
     "pydantic-settings>=2.6.1",
     "loguru>=0.7.3",
     "pyright>=1.1.390",
-    "basic-foundation",
     "markdown-it-py>=3.0.0",
     "python-frontmatter>=1.1.0",
     "rich>=13.9.4",
     "unidecode>=1.3.8",
     "dateparser>=1.2.0",
     "watchfiles>=1.0.4",
+    "fastapi[standard]>=0.115.8",
+    "alembic>=1.14.1",
 ]
 
 [project.optional-dependencies]

{basic_memory-0.0.0 → basic_memory-0.1.0}/src/basic_memory/api/app.py

@@ -7,18 +7,40 @@ from fastapi.exception_handlers import http_exception_handler
 from loguru import logger
 
 from basic_memory import db
-from .routers import knowledge, search, memory, resource
+from basic_memory.api.routers import knowledge, search, memory, resource
+from basic_memory.config import config
+from basic_memory.services import DatabaseService
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Lifecycle manager for the FastAPI app."""
     logger.info("Starting Basic Memory API")
+    
+    # check the db state
+    await check_db(app)
     yield
     logger.info("Shutting down Basic Memory API")
     await db.shutdown_db()
 
 
+async def check_db(app: FastAPI):
+    logger.info("Checking database state")
+
+    # Initialize DB management service
+    db_service = DatabaseService(
+        config=config,
+    )
+
+    # Check and initialize DB if needed
+    if not await db_service.check_db():
+        raise RuntimeError("Database initialization failed")
+
+    # Clean up old backups on shutdown
+    await db_service.cleanup_backups()
+
+
+
 # Initialize FastAPI app
 app = FastAPI(
     title="Basic Memory API",