memory-infrastructure-palace/.github/copilot-instructions.md

GitHub Copilot Instructions for Memory Palace

Project Overview

This is a hybrid workspace combining:

• Documentation: Obsidian-style knowledge management with wiki-links and backlinks
• Code Development: Bookmarklets, scratchpad code, and project prototypes

Documentation Guidelines

Writing Style

• Use clear, concise markdown
• Employ wiki-style [[links]] for connecting notes
• Include frontmatter metadata in notes (date, type, tags)
• Keep daily notes in /docs/daily/ with format daily-YYYY-MM-DD.md
• Place evergreen concept notes in /docs/concepts/

Note Structure

---
type: concept|project|fleeting
created: YYYY-MM-DD
tags: []
---

# Title

## Overview

Brief summary

## Content

Main content with [[links]]

## Related

- [[other-note]]

Code Development Guidelines

Bookmarklets (/code/bookmarklets/)

• Write as regular Node.js-compatible JavaScript files
• Use modern ES6+ syntax, let/const, etc. (will be minified)
• Include JSDoc comments for documentation (removed in final bookmarklet)
• Write clear, readable code - the generator handles minification
• Use descriptive variable and function names
• Test logic in Node.js if possible before converting

Conversion Process:

1. Write bookmarklet as normal .js file in /code/bookmarklets/
2. Run: npm run bookmarklet -- code/bookmarklets/your-file.js
3. Generator automatically:
   • Removes all comments
   • Minifies code
   • Wraps in IIFE: javascript:(function(){...})();
   • Copies to clipboard
4. Paste into browser bookmark URL field

Scratchpad Code (/code/scratchpad/)

• This is experimental space - be creative
• Add TODO: comments for work in progress
• Use descriptive variable names
• Include usage examples
• Python: Follow PEP 8 style
• JavaScript/TypeScript: Use modern ES6+ syntax

Code Style

• Python: PEP 8, type hints preferred
• JavaScript: Modern ES6+, const/let over var, ES modules (import/export)
• TypeScript: Explicit types, interfaces over types
• Comments: Explain why, not what
• Functions: Single responsibility, descriptive names

Module System

This project uses ES modules (import/export), not CommonJS (require).

• Use import for dependencies: import fs from 'fs';
• Use export for exporting: export default myFunction; or export { myFunction };
• Package.json is configured with "type": "module"
• Use .js extension for ES modules
• For Node.js built-ins requiring special handling: import { fileURLToPath } from 'url';

File Organization

When to Create Files

• Fleeting notes: Quick captures, temporary thoughts → /docs/fleeting/
• Concept notes: Refined ideas, evergreen content → /docs/concepts/
• Project docs: Specific project documentation → /docs/projects/
• Bookmarklets: Browser utilities → /code/bookmarklets/
• Experiments: Testing/learning → /code/scratchpad/

Naming Conventions

• Documentation: kebab-case.md (e.g., my-note.md)
• JavaScript: kebab-case.js (e.g., my-bookmarklet.js)
• Python: snake_case.py (e.g., my_script.py)
• TypeScript: kebab-case.ts (e.g., my-module.ts)

Git Commit Practices

GitDoc auto-commits on save. For manual commits:

• Use conventional commits: type: description
• Types: docs:, feat:, fix:, refactor:, chore:
• Examples:
  • docs: add note on memory techniques
  • feat: create bookmark highlighter bookmarklet
  • fix: correct regex in search bookmarklet

Special Considerations

Cross-Linking

When suggesting note connections:

• Look for conceptual relationships
• Suggest bidirectional links
• Consider creating index notes for related topics

Code Reusability

• Create templates in /code/templates/ for common patterns
• Extract reusable functions into utility modules
• Document APIs and interfaces

Search & Discovery

• Use descriptive titles and headers
• Include relevant tags in frontmatter
• Add aliases for alternative terms
• Consider TODO tags: TODO:, FIXME:, NOTE:, IDEA:

Preferences

• Brevity: Favor concise, clear explanations
• Examples: Include practical examples in code
• Context: Assume this is a personal knowledge workspace
• Flexibility: This is a scratchpad - prioritize exploration over perfection
• Learning: Explain concepts when introducing new patterns or techniques

README Maintenance

IMPORTANT: Keep README files synchronized with project structure changes.

When to Update READMEs

Update relevant README.md files whenever you:

• Add or remove folders
• Change file organization
• Add new tools or utilities
• Modify workflows or conventions
• Add new features or capabilities

README Locations

• /README.md - Main project overview and quick start
• /docs/README.md - Documentation hub and note-taking guide
• /code/README.md - Code section overview
• /code/bookmarklets/README.md - Bookmarklet creation guide
• /.github/README.md - GitHub templates and structure

Update Guidelines

• Keep structure diagrams accurate
• Update examples to reflect current patterns
• Maintain consistency across all READMEs
• Add new sections before implementation when adding major features
• Remove outdated information immediately

Tools & Extensions Available

• Foam (wiki-links, backlinks, graph)
• Code Runner (quick code execution)
• Todo Tree (tracks TODO comments)
• Bookmarks (mark important code locations)
• ESLint (JavaScript linting)