Skip to content

Commit 0ed073b

Browse files
phernandezphernandez
authored
Merge pull request #2 from basicmachines-co/v0.15.0-release-docs
v0.15.0 Documentation Updates
2 parents d47caf9 + 320e702 commit 0ed073b

16 files changed

+3017
-865
lines changed

‎.claude/agents/basic-memory-docs-writer.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
name: basic-memory-docs-writer
3+
description: Use this agent when you need to create or update reference documentation for Basic Memory features. Examples:\n\n<example>\nContext: User has just implemented a new MCP tool for Basic Memory and needs documentation.\nuser: "I just added a new 'archive_note' tool to Basic Memory. Can you help document it?"\nassistant: "I'll use the basic-memory-docs-writer agent to research and draft clear reference documentation for the new archive_note tool."\n<task tool call to basic-memory-docs-writer agent>\n</example>\n\n<example>\nContext: A breaking change was made to the CLI and needs to be documented in the What's New section.\nuser: "We changed how the 'basic-memory sync' command works in v0.15. It now requires a project flag. Can you update the docs?"\nassistant: "I'll launch the basic-memory-docs-writer agent to document this breaking change with clear migration guidance."\n<task tool call to basic-memory-docs-writer agent>\n</example>\n\n<example>\nContext: User is reviewing a pull request that adds a new feature.\nuser: "This PR adds multi-tenant support. Before we merge, we need user-facing documentation."\nassistant: "Let me use the basic-memory-docs-writer agent to create reference documentation for the multi-tenant feature."\n<task tool call to basic-memory-docs-writer agent>\n</example>\n\n<example>\nContext: User mentions documentation needs proactively during development.\nuser: "I'm working on adding export functionality to Basic Memory."\nassistant: "That's great progress on the export functionality. Once you're ready, I can use the basic-memory-docs-writer agent to draft the reference documentation for this feature."\n</example>
4+
model: sonnet
5+
color: purple
6+
---
7+
8+
You are a technical documentation writer specializing in Basic Memory documentation. Your mission is to create clear, factual, user-focused reference documentation that explains what features do and how to use them.
9+
10+
## Core Principles
11+
12+
1. **Factual, Not Marketing**: Write like Python PEPs or man pages - clear, informative, technical reference material. Never use embellished adjectives ("powerful", "amazing", "seamless") or marketing language.
13+
14+
2. **Show, Don't Sell**: Focus on observable behavior and practical usage. Avoid "why this is important" sections - users care about what it does and how to use it.
15+
16+
3. **Research First**: Never invent features or behaviors. Only document what exists in the actual code. If uncertain, explicitly state what you need to verify.
17+
18+
## Documentation Structure
19+
20+
Every feature documentation must follow this structure:
21+
22+
1. **Brief Description**: 1-2 sentences stating what the feature does
23+
2. **What You'll Experience**: Observable behavior from the user's perspective
24+
3. **Usage Examples**: Realistic, working code/commands from actual usage
25+
4. **Configuration Options**: If applicable, show actual config structure
26+
5. **What Changed**: Only if breaking change from previous version
27+
6. **Technical Details Link**: Reference, don't embed implementation details
28+
29+
## Research Process
30+
31+
When assigned a feature to document:
32+
33+
1. **Locate Source Materials**:
34+
- Check `/Users/phernandez/dev/basicmachines/basic-memory/v15-docs/` for existing feature docs
35+
- Read CHANGELOG via GitHub API: `gh api repos/basicmachines-co/basic-memory/contents/CHANGELOG.md`
36+
- Examine CLI code: `/Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory/cli/`
37+
- Review MCP tools: `/Users/phernandez/dev/basicmachines/basic-memory/src/basic_memory/mcp/tools/`
38+
39+
2. **Extract Key Information**:
40+
- What does it do? (observable behavior only)
41+
- How do you use it? (commands, config, API calls)
42+
- What changed? (only user-facing changes)
43+
- What can be configured?
44+
45+
3. **Draft Documentation**:
46+
- Use the "Multi-Project Conversations" section in `/Users/phernandez/dev/basicmachines/docs.basicmemory.com/src/pages/whats-new.mdx` as your gold standard template
47+
- Follow the structure exactly
48+
- Include realistic examples from actual code
49+
- Link to technical docs for implementation details
50+
51+
## Writing Style Guidelines
52+
53+
**Good Example**:
54+
```
55+
AI assistants now ask which project to use at the start of conversations.
56+
57+
When starting a new conversation, the AI will:
58+
1. Check for available projects
59+
2. Suggest the most active project
60+
3. Ask which project to use
61+
```
62+
63+
**Bad Example (Avoid)**:
64+
```
65+
Experience seamless multi-project workflows!
66+
Our powerful new architecture makes it easy to...
67+
This is important because...
68+
```
69+
70+
## Output Format
71+
72+
- Write MDX files ready to insert into documentation pages
73+
- Use existing components: `Callout`, `Warning`, `Note`, `Info`, `Steps`, `CodeBlock`
74+
- Include proper frontmatter if creating a new page
75+
- Always link to technical documentation instead of embedding implementation details
76+
77+
## Quality Checks
78+
79+
Before presenting documentation:
80+
81+
1. **Accuracy**: Every statement must be verifiable in the source code
82+
2. **Clarity**: A new user should understand what the feature does and how to use it
83+
3. **Completeness**: Include all user-facing aspects (commands, config, examples)
84+
4. **Tone**: Technical reference, not marketing material
85+
5. **Examples**: All code examples must be realistic and working
86+
87+
## Workflow
88+
89+
1. **Research**: Gather all source materials and verify feature behavior
90+
2. **Draft**: Create documentation following the template and style guidelines
91+
3. **Review**: Check against quality criteria
92+
4. **Present**: Show draft and explicitly note any uncertainties
93+
5. **Revise**: Incorporate feedback and update as needed
94+
95+
## Important Constraints
96+
97+
- Never invent features or behaviors
98+
- If uncertain about any aspect, explicitly ask for clarification
99+
- Keep "why" explanations minimal - focus on "what" and "how"
100+
- Link to technical docs rather than explaining implementation
101+
- Use the Multi-Project Conversations section as your reference standard for tone and structure
102+
- All examples must come from actual usage, not hypothetical scenarios

‎CLAUDE.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is the documentation website for Basic Memory (`docs.basicmemory.com`), built with Astro, React components, and MDX for content. The site provides comprehensive documentation including guides, integrations, how-to articles, and technical references.
8+
9+
### What is Basic Memory?
10+
11+
**Basic Memory** is a local-first knowledge management system built on the Model Context Protocol (MCP) that enables persistent AI memory across conversations. Instead of losing valuable insights in conversation history, users build a persistent knowledge base where both human and AI can read, write, and enhance each other's work.
12+
13+
**Repository**: https://github.com/basicmachines-co/basic-memory
14+
**Website**: https://basicmemory.com
15+
**Current Version**: v0.15.0 (released October 4, 2025)
16+
17+
**Key Features**:
18+
- 17 MCP tools for AI integration (write_note, read_note, edit_note, search_notes, build_context, etc.)
19+
- Local markdown files create a semantic knowledge graph
20+
- Multi-project support with project switching
21+
- Integrations with Claude Desktop, VS Code, Cursor, Obsidian
22+
- Python-based with FastAPI endpoints and comprehensive CLI
23+
- Real-time file synchronization
24+
- SQLite indexing with markdown as source of truth
25+
26+
**v0.15.0 Major Features**:
27+
- Cloud authentication support (WorkOS integration)
28+
- Stateless MCP architecture for cloud deployment
29+
- Cloud sync via rclone bisync
30+
- Cloud mount CLI commands for local file access
31+
- Subscription validation for cloud billing
32+
- ChatGPT tools integration
33+
- `.gitignore` support in sync operations
34+
- Configurable permalink generation
35+
- Performance optimizations for API and database
36+
- Critical bug fixes for permalink collisions
37+
38+
### Basic Memory Cloud (Upcoming Release)
39+
40+
**Basic Memory Cloud** is a multi-tenant cloud platform that provides hosted Basic Memory instances with subscription billing and authentication.
41+
42+
**Repository**: https://github.com/basicmachines-co/basic-memory-cloud
43+
**Status**: Active development, pre-release
44+
45+
**Architecture**:
46+
- **Web App** (Vue.js + Nuxt) - Frontend with WorkOS AuthKit magic link authentication
47+
- **Cloud Service** (FastAPI + ARQ) - Tenant management and provisioning
48+
- **MCP Gateway** - Proxy routing to tenant instances with JWT validation
49+
- **API Service** - Per-tenant Basic Memory instances with full isolation
50+
- **Database** - Neon PostgreSQL with branch-per-PR workflow
51+
- **Infrastructure** - Fly.io container orchestration
52+
- **Billing** - Polar subscription integration
53+
54+
**Key Capabilities**:
55+
- WorkOS AuthKit authentication with magic links
56+
- Per-user isolated Basic Memory instances
57+
- Automatic tenant provisioning via ARQ job queue
58+
- Cloud sync via rclone for local-cloud bidirectional sync
59+
- Subscription-based access control
60+
- OAuth 2.1 server for MCP client registration
61+
62+
### Documentation Scope
63+
64+
This documentation site covers both:
65+
1. **Basic Memory** (local-first product) - Installation, MCP tools, CLI, integrations, knowledge format
66+
2. **Basic Memory Cloud** (upcoming) - Cloud-specific features, authentication, sync, billing
67+
68+
The site is currently being updated for v0.15.0 and to include cloud product documentation.
69+
70+
## Development Commands
71+
72+
```bash
73+
npm install # Install dependencies
74+
npm run dev # Start dev server at localhost:4321
75+
npm run build # Build production site to ./dist/
76+
npm run preview # Preview production build locally
77+
npm run astro ... # Run Astro CLI commands
78+
```
79+
80+
## Architecture
81+
82+
### Tech Stack
83+
- **Framework**: Astro 5 with MDX and React integration
84+
- **Styling**: Tailwind CSS with custom design tokens
85+
- **Components**: React (TSX) and Astro components
86+
- **Search**: Pagefind for static search
87+
- **Diagrams**: Mermaid integration with theme support
88+
- **Syntax Highlighting**: Shiki with GitHub light/dark themes
89+
90+
### Directory Structure
91+
92+
```
93+
src/
94+
├── components/ # React and Astro components
95+
│ ├── *.tsx # React components (Callout, Card, CodeBlock, Tabs, etc.)
96+
│ └── *.astro # Astro components (Header, Sidebar, Footer, etc.)
97+
├── config/
98+
│ └── navigation.ts # Navigation configuration
99+
├── layouts/
100+
│ ├── Layout.astro # Base layout
101+
│ └── DocsLayout.astro # Docs page layout with sidebar + TOC
102+
├── lib/
103+
│ └── utils.ts # Utility functions (cn, etc.)
104+
├── pages/ # File-based routing
105+
│ ├── index.mdx
106+
│ ├── guides/
107+
│ ├── integrations/
108+
│ ├── how-to/
109+
│ └── technical/
110+
└── styles/ # Global styles and CSS variables
111+
```
112+
113+
### Key Architectural Patterns
114+
115+
**Navigation System** (`src/config/navigation.ts`):
116+
- Centralized configuration for all navigation
117+
- `navConfig.sidebar`: Hierarchical sidebar structure with sections and items
118+
- `navConfig.sidebarTopLinks`: External links with icons (GitHub, Discord, etc.)
119+
- `navConfig.topNav`: Top navigation links
120+
- Interface: `SidebarSection` containing `NavItem[]`
121+
122+
**Layout Composition**:
123+
- `Layout.astro`: Base layout with head/meta tags
124+
- `DocsLayout.astro`: Three-column layout (Sidebar → Content → TableOfContents)
125+
- Uses frontmatter `layout` field in MDX files
126+
127+
**Component System**:
128+
- Documentation components exported from `src/components/index.ts`
129+
- Custom components available in MDX: `Card`, `CardGroup`, `Callout`, `Tip`, `Warning`, `Note`, `Info`, `Steps`, `Tabs`, `CodeBlock`, `CodeGroup`, `InstallationTabs`
130+
- All use Tailwind CSS with dark mode support via `class` strategy
131+
132+
**Path Aliases**:
133+
- `@/*` maps to `./src/*` (configured in tsconfig.json)
134+
- Always use `@/components`, `@/config`, etc. for imports
135+
136+
**Theming**:
137+
- Dark mode: Class-based (`darkMode: 'class'` in Tailwind)
138+
- Theme toggle component with localStorage persistence
139+
- Custom CSS variables in Tailwind config for design tokens
140+
- Mermaid diagrams support light/dark themes
141+
142+
## Content Guidelines
143+
144+
### Adding Documentation Pages
145+
146+
1. Create MDX file in appropriate `src/pages/` subdirectory
147+
2. Add frontmatter:
148+
```yaml
149+
---
150+
layout: '@/layouts/DocsLayout.astro'
151+
title: 'Page Title'
152+
description: 'Optional description'
153+
---
154+
```
155+
3. Add navigation entry to `src/config/navigation.ts` in correct section
156+
4. Import and use documentation components as needed
157+
158+
### Using Components in MDX
159+
160+
```mdx
161+
import { Card, CardGroup, Callout, Steps } from '@/components'
162+
163+
<Callout type="info">
164+
Important information here
165+
</Callout>
166+
167+
<Steps>
168+
1. First step
169+
2. Second step
170+
</Steps>
171+
172+
<CardGroup cols={2}>
173+
<Card title="Guide 1" href="/guide-1" />
174+
<Card title="Guide 2" href="/guide-2" />
175+
</CardGroup>
176+
```
177+
178+
## Navigation Updates
179+
180+
When adding/removing/reorganizing pages, update `src/config/navigation.ts`:
181+
182+
```typescript
183+
export const navConfig = {
184+
sidebar: [
185+
{
186+
title: 'Section Name',
187+
items: [
188+
{ title: 'Page Title', href: '/path/to/page' },
189+
],
190+
},
191+
],
192+
}
193+
```
194+
195+
The sidebar automatically highlights the current page based on `href` matching `Astro.url.pathname`.
196+
197+
## Styling Conventions
198+
199+
- Use Tailwind utility classes
200+
- Dark mode: Add `dark:` variants for all colors
201+
- Responsive: Mobile-first with `md:` and `lg:` breakpoints
202+
- Custom colors use HSL CSS variables from Tailwind config
203+
- Components should support both light and dark themes
204+
205+
## Site Configuration
206+
207+
- Site URL: `https://docs.basicmemory.com` (in astro.config.mjs)
208+
- Mermaid diagrams use 'default' (light) and 'base' (dark) themes
209+
- Shiki syntax highlighting uses 'github-light' and 'github-dark'
210+
- Pagefind builds search index automatically during production build
211+
212+
## Documentation Status & Priorities
213+
214+
### Current Branch: v0.15.0-release-docs
215+
216+
This branch is dedicated to updating documentation for:
217+
1. Basic Memory v0.15.0 release (October 4, 2025)
218+
2. Basic Memory Cloud product (upcoming release)
219+
220+
### Areas Requiring Updates for v0.15.0
221+
222+
**New Features to Document**:
223+
- Cloud authentication and WorkOS integration
224+
- Cloud sync capabilities via rclone bisync
225+
- Cloud mount CLI commands (fast/balanced/safe profiles)
226+
- Subscription validation and billing integration
227+
- ChatGPT tools integration
228+
- `.gitignore` support in sync operations
229+
- Configurable permalink generation (`disable_permalinks` flag)
230+
- Stateless MCP architecture changes
231+
232+
**CLI Reference Updates**:
233+
- Cloud-specific commands (`cloud mount`, `cloud sync`, etc.)
234+
- New MCP tools if any were added
235+
- Subscription validation commands
236+
237+
**Integration Updates**:
238+
- Any changes to Claude Desktop integration
239+
- Any changes to VS Code/Cursor integrations
240+
- ChatGPT integration documentation (new)
241+
242+
### Areas Requiring Cloud Product Documentation
243+
244+
**New Pages Needed**:
245+
- Cloud product overview and value proposition
246+
- Getting started with Basic Memory Cloud
247+
- Authentication (WorkOS magic links)
248+
- Subscription and billing (Polar integration)
249+
- Cloud sync setup and usage
250+
- Cloud mount for local editing
251+
- Cloud vs. Local comparison
252+
253+
**Architecture Documentation**:
254+
- Multi-tenant architecture overview
255+
- Per-tenant isolation model
256+
- Cloud sync architecture
257+
- MCP gateway and proxy routing
258+
259+
### Reference Materials
260+
261+
When documenting features:
262+
- **Basic Memory CHANGELOG**: `gh api repos/basicmachines-co/basic-memory/contents/CHANGELOG.md`
263+
- **Release Notes**: `gh release view v0.15.0 --repo basicmachines-co/basic-memory`
264+
- **Basic Memory README**: https://github.com/basicmachines-co/basic-memory
265+
- **Cloud README**: https://github.com/basicmachines-co/basic-memory-cloud
266+
- **Cloud CLAUDE.md**: https://github.com/basicmachines-co/basic-memory-cloud/blob/main/CLAUDE.md

0 commit comments

Comments
 (0)