Complete memory approaches documentation restructuring

Major organizational improvements:
- Restructured memory approaches with consistent structure (README + prompts)
- Added 'Tracking Task Status Explicitly' section covering GitHub issues and .ongoing files
- Created 'AI Insights Comments' section for contextual memory in code
- Enhanced retaining-context.md with collaborative partnership framing
- Added 'Different audiences' section highlighting individual vs shared knowledge needs
- Removed redundant 'Per-project prompts' section from SUMMARY.md
- Updated all cross-references to new structure
- Applied voice alignment principles throughout

Key insights captured:
- Different audiences need both individual and shared memory systems
- Productive desynchronization as a feature (individual memory can drift from project)
- Need for organizational systems that avoid overwhelming Claude or humans

Documentation now provides clear navigation through memory experimentation approaches
while maintaining focus on practical collaborative partnership goals.

Author: nikomatsakis

src/SUMMARY.md

@@ -8,20 +8,21 @@
 - [User prompt](./prompts/user/README.md)
     - [main.md, the main prompt](./prompts/user/main.md)
     - [main.md v0, an older version](./prompts/user/main-v0.md)
-- [Per-project prompts](./prompts/project/README.md)
-    - [AI Insight comments](./prompts/project/ai-insights.md)
-    - [Github tracking issues](./prompts/project/github-tracking-issues.md)
-    - [.ongoing files](./prompts/project/ongoing-work-tracking.md)
 
 # Memory: Retaining context
 
 - [Retaining context](./retaining-context.md)
+- [Tracking Task Status Explicitly](./tracking-task-status/README.md)
+    - [GitHub Issues Prompt](./prompts/project/github-tracking-issues.md)
+    - [.ongoing Files Prompt](./prompts/project/ongoing-work-tracking.md)
+- [AI Insights Comments](./ai-insights-comments/README.md)
+    - [Prompt](./prompts/project/ai-insights.md)
 - [Official Memory Server](./official-memory-server/README.md)
+    - [Prompt](./prompts/project/official-memory-server.md)
 - [Custom Memory Bank](./memory-bank/README.md)
     - [Design Foundation](./memory-bank/design-foundation.md)
     - [Current State](./memory-bank/current-state.md)
     - [Frequently asked questions](./memory-bank/faq.md)
-- [AI Insights Comments](./prompts/project/ai-insights.md)
 
 # Dialectic
 

src/ai-insights-comments/README.md

@@ -0,0 +1,20 @@
+# AI Insights Comments
+
+Contextual memory embedded directly in code using structured comment annotations.
+
+## What It Provides
+- Non-obvious constraints and reasoning preserved in code
+- Context for future AI programming sessions
+- Decision boundaries and implementation tradeoffs
+- Algorithmic and architectural choices explained inline
+
+## The Approach
+Rather than external memory systems, this approach embeds collaborative insights directly where they're most relevant - in the code itself. Using `💡` comment annotations, we capture the reasoning behind implementation choices that aren't obvious from reading the code alone.
+
+This creates a form of contextual memory that travels with the code and provides immediate context when AI encounters it in future sessions.
+
+## Custom Prompt Integration
+The [AI Insights prompt](../prompts/project/ai-insights.md) guides Claude to systematically add these annotations during code generation and modification, ensuring that important reasoning doesn't get lost between sessions.
+
+## Status
+**Active experiment** - Testing whether inline contextual memory can reduce the need for external memory systems by preserving collaborative insights where they're most useful.

src/introduction.md

@@ -1,12 +1,10 @@
 # Introduction
 
-This repository explores techniques for making use of Claude Code, Q CLI, and other similar AI assistants. The part of this repository that is currently actionable is the collection of [prompts that I have found useful][prompts]. These include [prompts meant to be installed user-wide][user-prompts] and [prompts that can be configured per-project][project-prompts].
-
-[prompts]: https://github.com/nikomatsakis/socratic-shell/tree/main/prompts
+This repository explores techniques for making use of Claude Code, Q CLI, and other similar AI assistants. The part of this repository that is currently actionable is the collection of prompts that I have found useful. These include [prompts meant to be installed user-wide][user-prompts] and add-on prompts associated with [memory retention approaches][memory-approaches].
 
 [user-prompts]: https://github.com/nikomatsakis/socratic-shell/tree/main/prompts/user
 
-[project-prompts]: https://github.com/nikomatsakis/socratic-shell/tree/main/prompts/project
+[memory-approaches]: ./retaining-context.md
 
 The second part of this repository is source code towards an experimental memory system for retaining context across sessions more automatically. The memory system is designed as an MCP tool that integrates with the above prompts, using "hooks" to trigger memory operations.
 

src/memory-bank/current-state.md

@@ -1,5 +1,18 @@
 # Current State
 
+## Recent Progress
+
+### Documentation Restructuring (July 2025)
+- **Memory approaches organization**: Restructured documentation to organize memory approaches with consistent structure (main README + associated prompts)
+- **Retaining context improvements**: Enhanced introduction with collaborative partnership framing, added "Different audiences" section highlighting individual vs. shared knowledge needs
+- **Navigation cleanup**: Removed redundant "Per-project prompts" section, updated all cross-references to new structure
+- **Voice alignment**: Applied "Niko voice" principles throughout - practical over theoretical, direct about challenges, experience-driven
+
+### Key Insights Captured
+- **Different audiences need**: Recognition that memory systems must serve both individual collaboration history and shared project knowledge
+- **Productive desynchronization**: Individual memory can drift from project memory (e.g., out-of-date rustc knowledge) while still being useful
+- **Organizational systems**: Claude won't remember everything, so we need systems to pull context in on demand without overwhelming
+
 ## Open Questions
 
 ### Technical Implementation

src/official-memory-server/README.md

@@ -13,6 +13,11 @@ External knowledge graph memory using the official MCP memory server from the Mo
 - **Language**: TypeScript/Node.js
 - **Status**: Active experiment
 
+## Custom Prompt Integration
+Rather than using the memory server mechanically, we've fashioned a [custom prompt](../prompts/project/official-memory-server.md) that guides Claude to use it as an extension of presence-based collaboration. The prompt frames memory as "a living dimension of our relationship" that emerges naturally from consolidation moments, insight recognition, and checkpointing work.
+
+This approach treats the external knowledge graph not as a database to fill but as a way to preserve the collaborative understanding that develops between human and AI over time.
+
 ## Integration Notes
 Testing how external knowledge graphs support:
 - Organic memory updates during consolidation moments

src/prompts/project/anthropic-memory.md …rompts/project/official-memory-server.mdsrc/prompts/project/anthropic-memory.md renamed to src/prompts/project/official-memory-server.md src/prompts/project/anthropic-memory.md renamed to src/prompts/project/official-memory-server.md

@@ -1,32 +1,44 @@
 # Retaining Context
 
-Collaborative prompting works great until the context starts to run out or you end your session. Then you have to start all over again. I haven't found things like Claude Code's `/compact` command to be very effective, so I've been exploring alternatives.
+With collaborative prompting, you can build up good rapport with Claude - shared understanding, working patterns, and preferences for how to approach problems. But when you quit and return later, Claude has forgotten the specifics of what you were doing and details of what you like and don't like.
 
-## The Challenge: Multiple Types of Context
+## The Goal: Collaborative Partnership, Not Rigid Structure
 
-There are many different kinds of context to retain:
-- **Interaction preferences** - How you like to work with AI
-- **Project information** - Current state, goals, architecture decisions  
+The aim isn't to create a complex memory system that forces AI into rigid patterns. Instead, we want to preserve the collaborative relationship while leveraging AI's natural strengths - the ability to collect, digest, and synthesize information organically. 
+
+Rather than cognitive overhead from complex structures, we want memory that supports the natural flow of collaborative work: consolidation moments, insight recognition, and the gradual deepening of shared understanding.
+
+## Different Types of Context Need Different Approaches
+
+Context retention isn't one problem but several:
+- **Interaction preferences** - How you like to work with AI. Sometimes a pattern is so broad that we extend the user prompt, but memory systems can be helpful for finer-grained details.
+- **Project information** - Current state, goals, architecture decisions.
 - **Shared code knowledge** - How things work that should benefit everyone
 - **Personal insights** - Your individual journey and understanding
 
-## Current Approaches
+## Different audiences
 
-### Explicit Context Management
-Claude and I maintain our context explicitly, either in [files for each ongoing task](./prompts/project/ongoing-work-tracking.md) or, more recently, through [AI-managed tracking issues on GitHub](./prompts/project/github-tracking-issues.md). When we come up with good new ideas or finish some phase of the work, I ask Claude to checkpoint our progress and they create commits and summarize our progress. Then we can always reload and figure out where we were.
+One of my key goals is to figure out how to fit Claude into existing project workflows, particularly open source workflows. I want to be able to retain *both* individual memory that is tailored to what *you* have done and to separate out general knowledge that can be useful to everyone. I believe that, just like humans, Claude won't be able to remember everything all of the time, so we need organizational systems that let us pull things in on demand and avoid overwhelming Claude (or the human!). 
 
-### Interaction Pattern Memory
-Tracking issues work pretty well for *tasks* but don't really capture changes to the *way* we interact. Right now, I've found that my [user prompt](./prompts/user/README.md) is a great start, though it helps to begin each fresh Claude session with "Hi again, Claude!", which triggers Claude to review the patterns with me. That creates a more spacious mood from the outset - not loading information, but setting the quality of attention we bring to the work.
+It's also useful sometimes for the memory of an individual to drift from the memory of the project -- for example, much of my memory about rustc is out-of-date when it comes to the particular project structure, but it'd still be useful for Claude to remember what we last saw and be updated with the latest version. Then it can advise me that something has changed since I last looked at it.
 
-### Quote-Based Systems
-I admire the systems used by [Yehuda Katz][] and [Kari Wilhelm][], two fellow travelers in this journey, who have asked Claude to record salient quotes and insights during sessions into a file, then reload that file at startup to 'recreate the soul' of previous work. This is very appealing and something I want to try.
+## Current Approaches
+
+### [Explicit Context Management](./tracking-task-status/README.md)
+To track the state of tasks, explicit context management seems to work pretty well. Claude and I maintain our context explicitly, either through [AI-managed tracking issues on GitHub](./tracking-task-status/README.md) or the older approach of [files for each ongoing task](./tracking-task-status/README.md). When we come up with good new ideas or finish some phase of the work, I ask Claude to checkpoint our progress and they create commits and summarize our progress. Then we can always reload and figure out where we were.
+
+### [AI Insights Comments](./ai-insights-comments/README.md)
+[AI insights comments](./ai-insights-comments/README.md) retain knowledge directly in code that will be needed when later editing the code. Using `💡` comment annotations, we capture non-obvious constraints, reasoning, and implementation tradeoffs right where they're most relevant. This is an example of encoding memory for others to find in a natural way - the context travels with the code itself.
 
 ### MCP Memory Systems
-At the more sophisticated end of the spectrum are various MCP memory systems. I have been exploring this space - see [Memory Experimentation](./memory-experimentation.md) for details on the different approaches I'm testing, including an experimental custom memory bank and the official MCP memory server.
+At the more sophisticated end of the spectrum are various MCP memory systems. I have two ongoing experiments: 
+
+1. [Adapting the official MCP memory server](./official-memory-server/README.md) for use with collaborative prompting.
+2. Experimenting with building a [custom memory bank](./memory-bank/README.md) server.
 
 ## Status
 
-This area is very much in flux. With so many existing solutions and the promising simplicity of the quote-based approaches, I may pivot to adapting existing work rather than building from scratch. The key insight is that different types of context may need different retention strategies.
+This area is very much in flux. The key insight is that different types of context may need different retention strategies.
 
 [Yehuda Katz]: https://www.linkedin.com/in/yehudakatz/
 [Kari Wilhelm]: https://www.linkedin.com/in/kariwilhelm/

src/retaining-context.md

@@ -0,0 +1,27 @@
+# Tracking Task Status Explicitly
+
+Using structured files and GitHub issues to maintain context across work sessions.
+
+## What It Provides
+- Persistent task state that survives session boundaries
+- Clear scope definition for multi-session work
+- Progress tracking and session continuity
+- Natural integration with existing development workflows
+
+## Two Approaches
+
+### GitHub Issues (Current)
+Using GitHub issues as living documents with specific conventions. Each substantial feature gets a tracking issue where the Original Post maintains current status and comments capture session details.
+
+### .ongoing Files (Legacy)
+File-based approach where each ongoing task gets a dedicated `.ongoing` file in the project directory to track progress and context.
+
+## Key Benefits
+This explicit context management works well because both human and AI can reference and update the same structured information, providing reliable continuity across sessions without requiring specialized infrastructure.
+
+## Custom Prompt Integration
+- [GitHub Issues prompt](../prompts/project/github-tracking-issues.md) - Current approach with detailed conventions
+- [.ongoing Files prompt](../prompts/project/ongoing-work-tracking.md) - Legacy file-based approach
+
+## Status
+**Working approach** - Explicit task tracking has proven effective for maintaining context. The GitHub issues approach is currently preferred over the older file-based system.