Code Project Documentation

Use Basic Memory to create and maintain comprehensive project documentation alongside your code

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": "[e-mail]",
  "password": "securepassword"
}

### Response Format
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 3600,
  "user": {
    "id": "123",
    "email": "[e-mail]",
    "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

1. Use semantic patterns - Employ observations with categories and tags
2. Create rich relations - Link related concepts extensively
3. Include code examples - Show practical implementations
4. Document decisions - Capture the “why” not just the “what”
5. Keep it current - Update docs with code changes

​

Organization Tips

1. Consistent naming - Use kebab-case for file names
2. Clear hierarchy - Organize by functional areas
3. Template usage - Create templates for common document types
4. Regular reviews - Schedule documentation review sessions
5. Git integration - Version control documentation with code

​

Team Collaboration

1. Shared vocabulary - Use consistent terminology across docs
2. Review process - Include documentation in code reviews
3. Onboarding guides - Create clear paths for new team members
4. Knowledge sharing - Regular documentation sessions
5. Tool 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

Architecture Decisions

Learn to document technical decisions effectively

Note Taking

Master note-taking techniques for development

Knowledge Format

Understand Basic Memory’s semantic patterns

CLI Reference

Master command line tools for documentation