Basic Memory excels at creating living documentation that evolves with your project. By co-locating documentation with code and using structured semantic patterns, you can maintain comprehensive project knowledge that stays current and useful.
Getting Started Setting Up Project Documentation Create a Basic Memory project within your codebase:
# Create docs folder in your project mkdir docs # Initialize Basic Memory project basic-memory project add my-project ~/code/my-project/docs # Start working cd ~/code/my-project Example Folder Structure my-project/ ├── src/ ├── tests/ ├── docs/ # Basic Memory knowledge base │ ├── architecture/ │ │ ├── system-overview.md │ │ ├── database-design.md │ │ └── api-design.md │ ├── decisions/ │ │ ├── adr-001-framework-choice.md │ │ ├── adr-002-database-selection.md │ │ └── template.md │ ├── guides/ │ │ ├── setup.md │ │ ├── development.md │ │ └── deployment.md │ ├── patterns/ │ │ ├── error-handling.md │ │ ├── validation.md │ │ └── testing.md │ └── api/ │ ├── authentication.md │ ├── endpoints.md │ └── models.md └── README.md Documentation Patterns System Architecture Documentation Document your system’s architecture with observations and relations:
--- title : System Architecture Overview tags : [ architecture , system-design ] --- # System Architecture Overview ## Components ### Frontend - [ component ] React application with TypeScript #frontend - [ responsibility ] User interface and client-side logic #ui - [ technology ] Vite for build tooling #build ### Backend API - [ component ] FastAPI Python service #backend - [ responsibility ] Business logic and data access #api - [ technology ] PostgreSQL database with SQLAlchemy #database ### Infrastructure - [ component ] Docker containers for deployment #infrastructure - [ responsibility ] Service orchestration and scaling #deployment - [ technology ] Kubernetes for container management #kubernetes ## Data Flow - [ flow ] Client requests → API Gateway → Backend Service #data-flow - [ pattern ] Request/Response with JSON payloads #api-pattern - [ security ] JWT authentication for protected endpoints #auth ## Relations - implements [[API Design Principles]] - uses [[Database Schema]] - deployed_via [[Kubernetes Configuration]] - follows [[Security Guidelines]] API Documentation Document APIs with practical examples and technical details:
--- title : User Authentication API tags : [ api , authentication , endpoints ] --- # User Authentication API ## POST /auth/login ### Purpose - [ endpoint ] User authentication and session creation #auth - [ input ] Email and password credentials #credentials - [ output ] JWT access token and refresh token #tokens ### Request Format { "email": "user@example.com", "password": "securepassword" } ### Response Format { "access_token": "eyJ...", "refresh_token": "eyJ...", "expires_in": 3600, "user": { "id": "123", "email": "user@example.com", "name": "John Doe" } } ## Implementation Details - [ security ] Password hashing with bcrypt #security - [ validation ] Email format validation required #validation - [ rate-limiting ] Maximum 5 attempts per minute per IP #rate-limiting - [ storage ] Refresh tokens stored in Redis #storage - [ expiry ] Access tokens expire in 1 hour #token-expiry ## Error Responses - [ error ] 400 - Invalid request format #validation-error - [ error ] 401 - Invalid credentials #auth-error - [ error ] 429 - Rate limit exceeded #rate-limit-error ## Relations - implements [[Authentication Strategy]] - uses [[User Model]] - requires [[Rate Limiting Middleware]] - validates_with [[Input Validation]] Architecture Decision Records (ADRs) Use Basic Memory’s semantic format for structured decision documentation:
--- title : "ADR-001: Database Technology Selection" tags : [ adr , database , decisions , postgresql ] --- # ADR-001: Database Technology Selection ## Status - [ status ] Accepted #decision-status - [ date ] 2024-01-15 #decision-date - [ impact ] High - affects entire data layer #impact ## Context We need to select a database technology for our financial application that handles user transactions, account balances, and reporting data. ## Decision Selected PostgreSQL over MongoDB and MySQL. ## Rationale ### Requirements Analysis - [ requirement ] ACID compliance for financial transactions #acid - [ requirement ] Complex analytical queries for reporting #analytics - [ requirement ] Strong consistency guarantees #consistency - [ requirement ] Mature ecosystem and tooling #ecosystem ### Technology Evaluation #### PostgreSQL (Selected) - [ advantage ] Full ACID compliance #acid - [ advantage ] Advanced SQL features (CTEs, window functions) #sql-features - [ advantage ] JSON support for flexible schemas #json - [ advantage ] Excellent Python/SQLAlchemy integration #python - [ advantage ] Strong performance for analytical queries #performance - [ consideration ] Requires SQL expertise in team #team-skills #### MongoDB - [ disadvantage ] Limited ACID guarantees across collections #acid-limitation - [ advantage ] Flexible schema design #schema-flexibility - [ disadvantage ] Complex analytical queries #query-complexity - [ consideration ] NoSQL learning curve for team #learning-curve #### MySQL - [ advantage ] ACID compliance #acid - [ disadvantage ] Limited analytical query features #analytics-limitation - [ advantage ] Wide ecosystem support #ecosystem - [ consideration ] Less advanced features than PostgreSQL #feature-gap ## Consequences ### Positive - [ benefit ] Strong data consistency for financial operations #consistency - [ benefit ] Powerful querying capabilities for reports #reporting - [ benefit ] Mature tooling and monitoring #tooling - [ benefit ] Team already has SQL expertise #team-alignment ### Negative - [ cost ] More complex setup than document databases #complexity - [ cost ] Requires careful schema design #schema-planning - [ mitigation ] Using Alembic for migration management #migration-strategy ### Neutral - [ impact ] Standard SQL patterns familiar to team #familiarity - [ impact ] Good performance characteristics for our scale #performance ## Implementation Notes - [ tool ] Using SQLAlchemy 2.0 for ORM #orm - [ tool ] Alembic for database migrations #migrations - [ tool ] asyncpg for async database connections #async - [ monitoring ] PostgreSQL-specific monitoring setup #monitoring ## Relations - affects [[Database Schema Design]] - requires [[Migration Strategy]] - implements [[Data Architecture]] - influences [[Performance Monitoring]] - supports [[Financial Transaction Processing]] Development Workflows Daily Documentation Practice Morning startup:
You (to AI): "What documentation updates are needed based on recent commits?" AI: [Reviews git log and suggests documentation updates] During development:
You: "Document the new user preference system we just implemented" AI: [Creates comprehensive documentation with code examples and relations] End of sprint:
You: "Update our architecture overview with the changes from this sprint" AI: [Reviews changes and updates architectural documentation] Code Review Integration Before creating PR:
# Check if documentation is current basic-memory tools search-notes --query "authentication system" # Update documentation echo "Updated authentication to support OAuth2 flows" | \ basic-memory tools write-note --title "Sprint 12 - Auth Updates" --folder "updates" During code review:
Reference specific architecture decisions: memory://decisions/database-choice
Link to relevant patterns: memory://patterns/error-handling
Check if new patterns need documentation
Team Knowledge Sharing Onboarding new developers:
--- title : Developer Onboarding Guide tags : [ onboarding , team , setup ] --- # Developer Onboarding Guide ## Essential Reading - [ architecture ] Start with [[System Architecture Overview]] #overview - [ decisions ] Review all [[ ADR ]] documents #decisions - [ patterns ] Study [[Coding Patterns]] we follow #patterns - [ api ] Understand [[API Design Principles]] #api ## Setup Checklist - [ ] Clone repository and run setup script - [ ] Install Basic Memory: `uv tool install basic-memory` - [ ] Sync documentation: `basic-memory sync` - [ ] Review architecture documents - [ ] Complete coding exercise - [ ] Pair with senior developer for first feature ## Key Concepts - [ pattern ] We use semantic documentation with observations #documentation - [ practice ] All architectural decisions are documented as ADRs #adr - [ practice ] API changes require documentation updates #api-docs - [ practice ] Complex business logic gets decision documentation #business-logic ## Relations - references [[System Architecture Overview]] - includes [[Development Setup Guide]] - requires [[Coding Standards]] Advanced Patterns Living Documentation Keep documentation synchronized with code changes:
## Database Schema Evolution ### Version 1.2 (Current) - [ change ] Added user_preferences table #schema-change - [ migration ] Migration 2024-01-15-add-preferences.sql #migration - [ breaking ] Removed deprecated profile_data column #breaking-change ### Version 1.1 - [ change ] Added indexes for performance #performance - [ migration ] Migration 2024-01-01-add-indexes.sql #migration ## Relations - documented_in [[Migration Guide]] - affects [[User Model]] - requires [[Database Migration Strategy]] Cross-Project Documentation Link related concepts across projects:
## Shared Components ### Authentication Library - [ component ] Shared across all microservices #shared-component - [ repository ] `basic-auth-lib` repository #repository - [ documentation ] See memory://shared/auth-library #cross-reference ### API Gateway Configuration - [ component ] Central routing and rate limiting #gateway - [ repository ] `api-gateway` repository #repository - [ documentation ] See memory://infrastructure/api-gateway #cross-reference ## Relations - uses [[Shared Authentication Library]] - configured_in [[API Gateway Project]] Integration with Git Use git hooks to maintain documentation:
# Pre-commit hook to check documentation currency #!/bin/bash # Check if any API files changed without corresponding docs update if git diff --cached --name-only | grep -q "^src/api/" ; then if ! git diff --cached --name-only | grep -q "^docs/api/" ; then echo "API changes detected. Please update API documentation." exit 1 fi fi Best Practices Documentation Standards
Use semantic patterns - Employ observations with categories and tagsCreate rich relations - Link related concepts extensivelyInclude code examples - Show practical implementationsDocument decisions - Capture the “why” not just the “what”Keep it current - Update docs with code changes
Organization Tips
Consistent naming - Use kebab-case for file namesClear hierarchy - Organize by functional areasTemplate usage - Create templates for common document typesRegular reviews - Schedule documentation review sessionsGit integration - Version control documentation with code
Team Collaboration
Shared vocabulary - Use consistent terminology across docsReview process - Include documentation in code reviewsOnboarding guides - Create clear paths for new team membersKnowledge sharing - Regular documentation sessionsTool training - Ensure team knows Basic Memory patterns
Common Document Types Templates API Endpoint Template:
--- title : [ Endpoint Name ] tags : [ api , endpoint-category ] --- # [Endpoint Name] ## Purpose - [ endpoint ] Brief description #category - [ input ] Input parameters #input - [ output ] Response format #output ## Implementation - [ method ] HTTP method and path #http - [ validation ] Input validation rules #validation - [ authorization ] Authentication requirements #auth ## Relations - implements [[API Design Pattern]] - uses [[Model Name]] Architecture Decision Template:
--- title : ADR-XXX : [ Decision Title ] tags : [ adr , category ] --- # ADR-XXX: [Decision Title] ## Status - [ status ] Proposed/Accepted/Deprecated #status ## Context [Background and problem statement] ## Decision [What was decided] ## Consequences - [ benefit ] Positive outcomes #benefit - [ cost ] Negative impacts #cost - [ mitigation ] How costs are addressed #mitigation ## Relations - affects [[Related Component]] - supersedes [[Previous ADR]] Troubleshooting Common Issues
Documentation getting out of sync with code
Solutions:
Implement git hooks to check documentation updates
Include documentation updates in pull request templates
Schedule regular documentation review sessions
Use Basic Memory search to find related docs when changing code
Team not following documentation patterns
Solutions:
Create clear documentation templates and examples
Include documentation quality in code review criteria
Provide team training on Basic Memory semantic patterns
Make documentation updates part of definition of done
Finding relevant documentation is difficult
Solutions:
Use consistent tagging strategy across all documents
Create overview documents that link to detailed topics
Use Basic Memory search with specific tag filters
Maintain an index of key documents for quick reference
Next Steps 
