# Ready-to-Use Memory Items for Pepper Memory Bank
**Status**: Copy and paste ready
**Purpose**: Add immediately to `~/memo/global-memories/`
**Date**: 2025-12-16
---
## File 1: python-standards-checklist.md
```markdown
# Python Coding Standards & Checklist
## Environment Setup (uv + conda)
### When to Use What
- **uv primary**: Python packages (pip replacement, 10-100x faster)
- **conda primary**: System-level deps (CUDA, ffmpeg, GDAL, Java)
- **Hybrid (recommended)**: conda env + uv inside env = best of both
### Setup Commands
```bash
# Project creation
uv init myproject && cd myproject && uv sync
# If system deps needed
conda create -n project python=3.11 cudatoolkit ffmpeg
source activate project
uv sync # Then use uv for Python packages
```
## Code Standards
### Type Hints (Required on Public APIs)
```python
def process(items: list[str], timeout: int = 30) -> dict[str, int]:
"""Process and return counts."""
```
### Error Handling (Custom Exceptions)
```python
class DataError(ValueError): pass
try:
process(data)
except DataError as e:
logger.error(f"Error: {e}", exc_info=True)
raise
```
### Testing (pytest, >= 80% coverage)
```python
def test_process_valid():
result = process(["a", "b"])
assert len(result) == 2
@pytest.mark.asyncio
async def test_async_operation():
result = await async_op()
assert result is not None
```
## Quality Gates
- [ ] Type hints on all public functions
- [ ] Docstrings (module, class, function)
- [ ] ruff check && mypy passing
- [ ] pytest >= 80% coverage
- [ ] No print() → use logger only
- [ ] No hardcoded secrets
- [ ] uv.lock committed (reproducibility)
## Research Code
- [ ] Random seed: np.random.seed(42)
- [ ] Config file with hyperparams
- [ ] Results logged to JSON
- [ ] Dataset versioned (Zenodo reference)
- [ ] Figures generated by script
```
---
## File 2: go-standards-checklist.md
```markdown
# Go Coding Standards & Checklist
## Project Setup
```bash
go mod init example.com/project
go get github.com/some/package
```
## Error Handling (CRITICAL)
### Always Wrap Errors
```go
// CORRECT
result, err := operation()
if err != nil {
return fmt.Errorf("operation: %w", err) // Wrap for context
}
// WRONG
if err != nil {
return err // Lost context
}
```
### Check Error Type
```go
if errors.Is(err, context.Canceled) {
log.Printf("Cancelled")
} else if errors.Is(err, context.DeadlineExceeded) {
log.Printf("Timeout")
}
```
## Context Usage (First Parameter Always)
```go
// CORRECT
func Fetch(ctx context.Context, id string) (Data, error) {
select {
case <-ctx.Done():
return nil, ctx.Err()
default:
}
// Implementation
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
}
// WRONG - no context parameter
func Fetch(id string) (Data, error) { ... }
```
## Interfaces (Consumer-Defined)
```go
// CORRECT - consumer defines
type Reader interface {
Read(p []byte) (n int, err error)
}
// WRONG - provider defines
// (provider has more methods than needed)
```
## Naming Conventions
```go
func PublicFunc() {} // Exported
func privateFunc() {} // Unexported
const MaxRetries = 3 // Constants
type HTTPServer struct {} // Acronyms uppercase
```
## Quality Gates
- [ ] go fmt applied
- [ ] go vet passing
- [ ] golangci-lint clean
- [ ] Errors wrapped with context
- [ ] Context passed to goroutines
- [ ] Table-driven tests written
- [ ] No bare error checking
## Concurrency Patterns
```go
// errgroup for parallel operations
g, ctx := errgroup.WithContext(context.Background())
g.Go(func() error { return worker1(ctx) })
g.Go(func() error { return worker2(ctx) })
if err := g.Wait(); err != nil { ... }
// Channels for communication
ch := make(chan Result, 10)
go func() {
defer close(ch)
ch <- Process()
}()
for r := range ch { ... }
```
```
---
## File 3: mcp-server-standards.md
```markdown
# MCP Server Standards & Checklist (2025)
## Architecture Principles
### Stateless
- No side-effects in prompts
- Side-effects → tools
- Deterministic: same input → same output
### Versioned (Semantic)
- MAJOR.MINOR.PATCH
- Breaking change → MAJOR
- New feature → MINOR
- Bug fix → PATCH
### Validated
- All inputs checked against JSON Schema
- Reject unknown arguments
- Fail fast with clear error messages
## Prompt Template Structure
```yaml
id: summarizer
version: 2.0.0
status: stable # or "canary", "deprecated"
owner: team-name
description: "Summarize with bullet points"
arguments:
type: object
required: [text]
properties:
text:
type: string
minLength: 50
maxLength: 20000
style:
type: string
enum: [bulleted, narrative]
additionalProperties: false
messages:
- role: system
content: "You are a concise summarizer."
- role: user
content: "{{text}}"
```
## Security
### OAuth 2.1 + RBAC
```yaml
scopes:
prompts:
summarizer:
stable: [read]
canary: [read, write] # Restricted
admin: [read, write, delete] # Admin only
```
### Input Sanitization
- Allow-list tool names
- Escape user input
- Validate argument types
## Performance & Monitoring
### Caching
- Cache compiled templates (with TTL)
- Batch idempotent operations
### OpenTelemetry
```python
tracer.start_as_current_span("tool/invoke")
span.set_attribute("tool.name", tool_name)
meter.record_histogram("duration_ms", duration)
```
### SLOs
- p95 latency < 1200ms
- Error rate < 2%
- Uptime > 99.9%
## Deployment
### Canary Pattern
- 90% traffic → Stable version
- 10% traffic → Canary version
- Monitor metrics, auto-promote on pass
### Version Lifecycle
1. Develop (local testing)
2. Canary (10% traffic, 24-48 hours)
3. Stable (100% traffic, production)
4. Deprecated (sunset timeline)
## Quality Gates
- [ ] JSON Schema validation on all arguments
- [ ] Version number incremented (semver)
- [ ] Canary deployed < 10% traffic
- [ ] SLO metrics monitored
- [ ] RBAC scopes enforced
- [ ] OpenTelemetry enabled
- [ ] Security review passed
```
---
## File 4: academic-research-standards.md
```markdown
# Academic Research Code Standards
## Reproducibility Checklist
- [ ] Random seed fixed: `np.random.seed(42)`
- [ ] uv.lock committed (exact versions)
- [ ] Hyperparams logged: `results/config.json`
- [ ] Results logged: `results/metrics.json`
- [ ] Dataset versioned: Zenodo DOI or git-lfs
- [ ] Figures generated by code (not manual)
- [ ] README has reproduction steps
## Project Structure
```
paper-2025/
├── paper.md # Manuscript
├── figures/
│ ├── fig1.pdf # Generated output
│ └── fig1_generate.py # Code that generates
├── code/
│ ├── src/
│ ├── pyproject.toml
│ ├── uv.lock # Commit this!
│ └── README.md # "uv sync && python reproduce.py"
├── data/
│ ├── raw/
│ ├── processed/
│ └── README.md # Source + DOI
├── results/
│ ├── config.json # Hyperparameters
│ ├── metrics.json # Model performance
│ └── tables/ # Output tables
└── reproduce.py # Single command to regenerate all
```
## Hyperparameter Logging
```python
import json
from datetime import datetime
config = {
"model": "resnet50",
"learning_rate": 0.001,
"batch_size": 32,
"epochs": 100,
"random_seed": 42,
"dataset_version": "v2.1"
}
results = {
"timestamp": datetime.now().isoformat(),
"train_loss": 0.23,
"val_accuracy": 0.87,
"hyperparams": config,
"code_version": "abc123def" # Git commit
}
with open("results/metrics.json", "w") as f:
json.dump(results, f, indent=2)
```
## Figure Generation
```python
# CORRECT - code generates figure
import matplotlib.pyplot as plt
def plot_results(metrics):
plt.figure(figsize=(8, 6))
plt.plot(metrics['epoch'], metrics['loss'])
plt.xlabel("Epoch")
plt.ylabel("Loss")
plt.savefig("figures/fig1.pdf")
# Call from reproduce.py
plot_results(metrics)
# WRONG - manually edited figures not reproducible
```
## Citation & Reproducibility
```bibtex
@article{author2024,
title={Research Title},
author={Author, A.},
journal={Journal},
year={2024},
doi={10.1234/example}
}
```
In code:
```python
# Based on [1]: Author (2024) https://doi.org/10.1234/example
# Implementation details in appendix A
```
## Experiment Tracking
Use Weights & Biases or MLflow:
```python
import wandb
wandb.init(project="research", config=config)
for epoch in range(epochs):
loss = train_epoch()
wandb.log({"loss": loss, "epoch": epoch})
```
Always log:
- Hyperparameters
- Code version (git commit)
- Dataset version
- Results (metrics, loss curves)
- Compute environment (GPU, memory)
```
---
## File 5: ai-context-memory.md
```markdown
# AI Context Engineering & Memory Strategy
## 3-Layer Context Model
### Layer 1: Instructional (Goals & Constraints)
- What you want (summarize, code, analyze)
- Constraints (word limit, format, scope)
- Quality criteria (accuracy, clarity, speed)
Example:
```
"Summarize this paper in 200 words.
Output: JSON with abstract, key findings, limitations.
Cite sources with DOIs."
```
### Layer 2: Knowledge (Domain Info)
- Relevant facts
- Code examples
- API documentation
- Data schemas
- Patterns
Example:
```
"Context about API:
- Endpoint: GET /users/{id}
- Response: { id: string, name: string, email: string }
- Errors: 404 (not found), 401 (unauthorized)"
```
### Layer 3: Tool (Available Functions)
- What functions/tools are available
- Parameters and types
- Expected outputs
- Limitations
Example:
```
"Available functions:
- read_file(path: str) -> str
- parse_json(text: str) -> dict
- write_file(path: str, content: str) -> bool"
```
## Memory Quality Gates
BEFORE storing memory, ask:
1. **Frequency**: Needed EVERY conversation?
- Yes → Store in .cursor/rules
- No → Store in Pepper Memory Bank
2. **Size**: Fits ONE paragraph (max)?
- Yes → OK for .cursor/rules
- No → Use Pepper Memory Bank
3. **Type**: Rule/pattern or task?
- Rule/pattern → Memorize
- Task/one-time → Don't memorize
## Context Window Management
```python
def estimate_tokens(text: str) -> int:
"""Rough estimate: 1 token ≈ 4 characters"""
return len(text) // 4
# Before sending to AI
system_tokens = estimate_tokens(system_prompt)
conversation_tokens = sum(estimate_tokens(msg) for msg in history)
available = 128000 - system_tokens - conversation_tokens
if available < 5000:
# Prune old messages or summarize history
history = summarize_old_messages(history)
```
## Prompt Optimization Checklist
### Specificity
- [ ] Use concrete examples (not "process data" → "sort CSV by timestamp")
- [ ] Define "success" explicitly
- [ ] Avoid ambiguous terms
### Task Segmentation
- [ ] Break into subtasks if > 3 steps
- [ ] Number steps clearly
- [ ] Define output after each step
### Context Budget
- [ ] Estimate remaining window
- [ ] Remove irrelevant details
- [ ] Prioritize recent info
### Error Mitigation
- [ ] Ask for reasoning before conclusion
- [ ] Request citations
- [ ] Explicit "if uncertain, say so"
## Memory Organization
```
.cursor/rules
├─ Patterns (1 paragraph, every conversation)
├─ Quick reference (common operations)
└─ Links to Pepper Memory
Pepper Memory Bank (~/memo/global-memories)
├─ coding-standards-v9-1.md (this file)
├─ procedures/ (multi-step guides)
├─ error-patterns.md (solutions)
└─ project-specific/ (custom patterns)
Global KB Archive (~/Code/global-kb)
├─ Old versions (quarterly rollback)
├─ Investigations (deep dives)
└─ Historical context (reference only)
```
```
---
## File 6: api-microservices-standards.md
```markdown
# API & Microservices Standards
## Design-First Approach
### Write OpenAPI Spec FIRST
1. Define endpoints (paths, methods)
2. Define request/response schemas
3. Define errors and status codes
4. Get team review
5. THEN write code
## Standard Endpoint Structure
### Request
```
GET /v1/users/{id}
Headers:
Authorization: Bearer <token>
X-Request-ID: <uuid>
```
### Response (200 OK)
```json
{
"data": {
"id": "user-123",
"name": "John",
"email": "john@example.com"
},
"meta": {
"request_id": "uuid-here",
"timestamp": "2025-12-16T15:30:00Z"
},
"errors": null
}
```
### Response (Error)
```json
{
"data": null,
"meta": {
"request_id": "uuid-here",
"timestamp": "2025-12-16T15:30:00Z"
},
"errors": [
{
"code": "INVALID_REQUEST",
"message": "Email is required",
"field": "email"
}
]
}
```
## Microservices Patterns
### API Gateway
```
Client → API Gateway → Service1
(auth) → Service2
(rate-limit) → Service3
```
### Circuit Breaker
```
CLOSED (normal)
↓ (50% errors for 30s)
OPEN (fail fast)
↓ (every 60s test)
HALF_OPEN (test request)
↓ (if OK)
CLOSED
```
### Retry with Exponential Backoff
```
Attempt 1: wait 1s
Attempt 2: wait 2s
Attempt 3: wait 4s
Attempt 4: wait 8s
Attempt 5: fail
```
## Quality Gates
- [ ] OpenAPI spec matches implementation
- [ ] X-Request-ID on all endpoints
- [ ] Structured error codes + messages
- [ ] Pagination implemented (limit, offset)
- [ ] Retry logic with backoff
- [ ] Circuit breaker for dependencies
- [ ] Rate limiting configured
- [ ] Database query timeouts set
- [ ] Health check endpoint
## Versioning Strategy
```
GET /v1/users # Version in URL (preferred)
GET /v2/users # Breaking changes → new version
OR
GET /users (with Accept header)
Header: Accept: application/vnd.company.v2+json
```
Commit to URL versioning (easier tracking, monitoring).
```
---
## How to Use These Files
### Step 1: Add to Pepper Memory
```bash
cd ~/memo/global-memories
# Copy each file
cat > python-standards-checklist.md << 'EOF'
[paste content from File 1 above]
EOF
cat > go-standards-checklist.md << 'EOF'
[paste content from File 2 above]
EOF
# Repeat for MCP, academic, AI context, API files
# Commit
git add -A
git commit -m "add: research-backed memory items for daily use"
```
### Step 2: Reference in .cursor/rules
```yaml
# AUTO-LOAD STANDARDS
Remember:
- memory_bank_read("global-memories", "python-standards-checklist.md")
- memory_bank_read("global-memories", "go-standards-checklist.md")
- memory_bank_read("global-memories", "mcp-server-standards.md")
- memory_bank_read("global-memories", "academic-research-standards.md")
- memory_bank_read("global-memories", "ai-context-memory.md")
- memory_bank_read("global-memories", "api-microservices-standards.md")
When user asks for [language] standards:
1. Load relevant file from memory
2. Extract applicable section
3. Show checklist or pattern
4. Suggest code example
```
### Step 3: Use in Daily Work
```
In Cursor:
"I'm starting a Go microservice"
Cursor will:
1. Load go-standards-checklist.md + api-microservices-standards.md
2. Show Go standards + API patterns
3. Generate example code matching standards
```
---
**All files ready to copy and use immediately.**
