Jun 9, 2026, 4:06 PM

2026-06-09 14:06:59 +00:00
parent c36ead5db0
commit bb6ff3a8c6
12 changed files with 454 additions and 0 deletions
@@ -0,0 +1,26 @@
+# Conventions
+
+Coding style, naming, and structural conventions for the Knowledge Base.
+
+## Language Convention
+
+- **Synthesis Layer Content**: Polish (Polski) is used for summaries, index listings, concepts, and log descriptions (matching the current Polish structure of `knowledge/`).
+- **Configuration & Schemas**: English is used for `GEMINI.md`, core repository schemas, and code/script names.
+
+## Formatting & Link Style
+
+- **WikiLinks**: Prefer double brackets `[[knowledge/path/to/page]]` or standard relative link `[[page]]` for connections in the synthesis layer (`knowledge/`).
+- **YAML Frontmatter**: When requested or appropriate, include metadata (tags, dates, source counts) at the top of markdown files.
+- **Kebab Case**: File names in `knowledge/concepts/` and `knowledge/entities/` must be kebab-case (e.g., `human-in-the-loop.md`, `sql-server.md`).
+
+## Log Bookkeeping
+
+- **Log Appends**: Always append new entries to the top of `knowledge/log.md` with format:
+  ```markdown
+  ## [YYYY-MM-DD] Ingest | Source Title
+  - Bulleted details of created or updated pages.
+  ```
+
+## Feynman Problems Alignment
+
+- **Central Alignment**: Every newly ingested raw file must be tested against the 12 Feynman Problems documented in `knowledge/feynman_problems.md`. If the content addresses or helps answer any of those questions, update the respective section in `knowledge/feynman_problems.md` with a direct link and concise insight.
@@ -0,0 +1,31 @@
+# Core Memory
+
+Top-level map and invariant rules for the LLM Knowledge Base repository.
+
+## Knowledge Base Architecture
+
+The project implements a personal knowledge base based on Andrej Karpathy's LLM Knowledge Base pattern and the 12 Feynman Problems.
+
+### Directory Layout
+
+- `raw/`: **Source of Truth**. Immutable. Contains original PDFs, clipped articles, transcripts, and personal notes.
+  - `raw/articles/`: Web articles and blog posts.
+  - `raw/inbox/`: New files to be processed/ingested.
+  - `raw/notes/`: Raw personal notes and ideas.
+  - `raw/transcripts/`: Audio/video transcripts.
+- `knowledge/`: **Synthesis Layer**. Generated and updated solely by LLM agent.
+  - `knowledge/sources/` or `knowledge/summaries/`: Individual summaries of ingested sources.
+  - `knowledge/entities/`: Specific pages for tools, organizations, and people (e.g., `[[knowledge/entities/n8n]]`).
+  - `knowledge/concepts/`: Analytical pages for core ideas and theories (e.g., `[[knowledge/concepts/human-in-the-loop]]`).
+  - `knowledge/indices/`: Lists grouping files by category.
+  - `knowledge/index.md`: Master catalog mapping knowledge domains.
+  - `knowledge/log.md`: Chronological journal of ingest/analysis operations.
+  - `knowledge/feynman_problems.md`: Master list of the 12 Feynman problems.
+- `GEMINI.md`: Configuration and instructions for Gemini CLI.
+
+## Deep Dive Memories
+
+- For technical tools, platform details, and runtimes, see `mem:tech_stack`.
+- For useful workspace utility scripts and commands, see `mem:suggested_commands`.
+- For naming standards, language conventions, and Markdown link styles, see `mem:conventions`.
+- For validation and verification procedures before completing tasks, see `mem:task_completion`.
@@ -0,0 +1,33 @@
+# Memory Maintenance
+
+## Discovery Model
+
+- Core principle: progressive discovery through references, building a graph of memories.
+- Initially, agents are provided with the list of all memories (names only).
+- Agents should read `mem:core` as the top-level entry point (graph root).
+  This memory should contain references to other memories covering major project domains.
+  The referenced memories shall, in turn, shall contain references to even more specific memories, and so on.
+  The depth of the graph shall depend on the project complexity.
+- Use topics/folders to group related memories in order to make the content structure explicit.
+  Folders can mirror project structure (e.g. modules like frontend/backend) or topics like debugging, architecture, etc.
+- Memory references must use a mem: prefix inside backticks, e.g. `mem:frontend/core`.
+  The surrounding text should clearly indicate when to read the memory/which content to expect.
+  The text should provide more precise guidance than the memory name alone, 
+  i.e. avoid a reference like "frontend debugging: `mem:frontend/debugging` and instead make clear which aspects of frontend debugging are covered.
+- Memories themselves should not contain information about when to read them; this is the responsibility of the referring memory.
+
+## Style
+
+Dense agent notes, not prose docs. Prefer invariants, terse bullets. 
+Avoid obvious context, rationale, and examples unless they prevent likely mistakes. 
+Keep guidance durable and generalizable, not task-local.
+
+## Add/update threshold
+
+Add or update memories only with stable, non-obvious project conventions that avoid complex rediscovery in the future.
+Do not add: quick-read facts; generic language/framework knowledge; one-off task notes; volatile line-level details; behavior likely to change soon.
+
+## Maintenance Actions
+
+- Renaming memories: References are updated automatically if handled via Serena's memory rename tool.
+- Checking for stale memories (e.g. after deletion): Call `serena memories check` for a report.
@@ -0,0 +1,36 @@
+# Suggested Commands
+
+Project and shell commands for development, utility, and maintenance tasks.
+
+## Maintenance Scripts (Windows PowerShell)
+
+- **Knowledge-base Terms Replacer**: Refactors old "wiki" references to "knowledge" across files and renames files containing "wiki":
+  ```powershell
+  powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\replace_knowledge.ps1
+  ```
+
+## File Search & Search Commands
+
+- **Find specific pattern in knowledge directory**:
+  ```powershell
+  Select-String -Path .\knowledge\**\*.md -Pattern "concept-pattern"
+  ```
+- **List files matching a glob recursively (using PowerShell)**:
+  ```powershell
+  Get-ChildItem -Path .\knowledge -Recurse -Filter *.md
+  ```
+
+## Git Commands
+
+- **Check current repository status**:
+  ```powershell
+  git status
+  ```
+- **Inspect changes in working tree**:
+  ```powershell
+  git diff HEAD
+  ```
+- **Check the 3 most recent commits to match style**:
+  ```powershell
+  git log -n 3
+  ```
@@ -0,0 +1,18 @@
+# Task Completion
+
+Steps and commands to execute when validating code changes or knowledge-base updates.
+
+## Verification Checklist
+
+1. **Broken Link Check**: Ensure all newly added `[[WikiLinks]]` are accurate and point to existing files.
+2. **Kebab-Case Naming**: Verify all created concept or entity files are named in kebab-case.
+3. **UTF-8 Encoding**: Ensure modified and created markdown files are written in UTF-8 format.
+4. **Consistency Script**: Run the text replacement script if naming or file paths were updated:
+   ```powershell
+   powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\replace_knowledge.ps1
+   ```
+5. **Memory Reference Checks**: Validate Serena onboarding memories using:
+   ```powershell
+   serena memories check
+   ```
+6. **Git Cleanliness**: Run `git status` to ensure only intended changes are modified and no unintended files are staged.
@@ -0,0 +1,21 @@
+# Tech Stack
+
+Technical details and tools used in the LLM Knowledge Base repository.
+
+## Environment & Platform
+
+- **Operating System**: Windows (win32)
+- **Primary Shell**: PowerShell
+
+## Core Technologies
+
+- **Content Format**: GitHub Flavored Markdown (GFM).
+- **Encoding**: UTF-8.
+- **PKM UI**: Obsidian (recommended local viewer and graph visualizer).
+- **Agent Orchestrator**: Gemini CLI (used for parsing raw files, maintaining links, updating synthesis pages).
+
+## Versioning & Configuration
+
+- No compilers, compilers pins, or heavy framework dependencies.
+- Git is used for version control of the markdown files, allowing revision history and branching.
+- Local custom script: `replace_knowledge.ps1` handles codebase-wide text replacements (specifically migrating old "wiki" terminology to "knowledge").