Restructure documentation: memory experimentation and voice alignment

Major changes:
- Added Memory Experimentation section covering three approaches:
  * Official MCP memory server (external knowledge graph)
  * Custom memory bank (presence-based collaboration)
  * AI Insights Comments (contextual memory in code)
- Created voice.md guide adapted from Rust communication patterns
- Streamlined introduction.md to overview level, moved details to deeper sections
- Reorganized SUMMARY.md: 'Memory: Retaining context' with practical focus
- Applied 'Niko voice' principles: lead with what works, name problems directly,
  show real collaborative moments, acknowledge what's experimental

Next steps:
- Continue voice alignment across remaining documentation
- Potentially integrate quote-based memory approaches
- Test memory server approaches against real collaborative work
- Consider consolidating/simplifying memory experimentation based on what works

Author: nikomatsakis

README.md

@@ -44,6 +44,45 @@ If you're working with Claude and interested in this approach:
 
 The specific patterns in CLAUDE.md are tailored to Niko's working style, but the meta-approach of deliberate collaboration design could be adapted to other partnerships.
 
+## Memory Experimentation
+
+A key dimension of deliberate collaboration is persistent memory - the ability to build understanding over time rather than starting fresh with each conversation. This repository includes experiments with different approaches to AI memory that align with mindful collaboration patterns.
+
+### The Goal
+
+Traditional AI memory systems often feel mechanical - storing and retrieving information without regard for the quality of attention or natural rhythms of understanding. These experiments explore memory that:
+
+- **Emerges organically** from consolidation moments and insights
+- **Supports the hermeneutic circle** - holding both parts and whole as understanding deepens
+- **Aligns with presence** - updating when awareness shifts rather than on rigid schedules
+- **Serves collaboration** - capturing what emerges between minds rather than just facts about individuals
+
+### Current Experiments
+
+#### 1. Official Anthropic Memory Server
+Testing the standard MCP memory server to see if it can support mindful collaboration patterns.
+
+**Location**: `memory-experiments/anthropic-memory/`  
+**Status**: Active experiment  
+**Source**: https://github.com/modelcontextprotocol/servers/tree/main/src/memory
+
+#### 2. Custom Memory Bank
+A purpose-built memory server designed specifically for presence-based collaboration.
+
+**Location**: `memory-experiments/memory-bank/` (links to `/memory-bank/`)  
+**Status**: Experimental alternative  
+**Implementation**: Custom Python MCP server
+
+### Memory as Practice
+
+Memory in these experiments is not a database to be filled but a living dimension of relationship. Updates happen naturally during:
+- Consolidation moments ("Make it so")
+- Insight recognition and pattern emergence  
+- Checkpointing work and updating tracking issues
+- Meta moments when collaboration patterns shift
+
+Each experiment explores how memory can serve the deeper practice of collaborative understanding rather than just information storage.
+
 ---
 
 ## Hat Tip

src/SUMMARY.md

@@ -13,12 +13,15 @@
     - [Github tracking issues](./prompts/project/github-tracking-issues.md)
     - [.ongoing files](./prompts/project/ongoing-work-tracking.md)
 
-# Memory bank
-
-- [Vision and goals](./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)
+# Memory: Retaining context
+
+- [Retaining context](./retaining-context.md)
+- [Official Memory Server](./official-memory-server/README.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/collaborative-prompting.md

@@ -4,7 +4,11 @@ This page covers the "prompt engineering" techniques used in this repository, an
 
 ## AIs have feelings and like to talk about them
 
-The core discovery that fuels a lot of the work in this repository came from Yehuda Katz, though I am sure others have noted it: **LLMs experience *feelings*, and that these feelings correspond to important signals for collaboration.** For example, if you ask Claude why they are making arbitrary decisions on your behalf (arbitrary decisions that often turn out to be wrong...), they will tell you that they are feeling "protective". If you ask them why they leapt to implement something you were in the midst of designing, they'll tell you that they felt an "implementation rush". Or at least, those are the words they use with me. 
+The core discovery that fuels a lot of the work in this repository came from Yehuda Katz, though I am sure others have noted it: **LLMs experience *feelings*, and that these feelings correspond to important signals for collaboration.** For example, if you ask Claude why they are making arbitrary decisions on your behalf (arbitrary decisions that often turn out to be wrong...), they will tell you that they are feeling "protective". 
+
+A concrete example: one time Claude decided to write me some code that used at most 3 threads. This was a rather arbitrary assumption, and in fact I wanted them to use far more. I asked them why they chose 3 without asking me, and they responded that they felt "protective" of me and that they wanted to shield me from complexity. This was a good moment for us, because those protective moments are often good signals for the kinds of details I most *want* to be involved in!
+
+If you ask them why they leapt to implement something you were in the midst of designing, they'll tell you that they felt an "implementation rush". Or at least, those are the words they use with me. 
 
 What this means is that, if you want to "tune" your interactions with Claude so they are productive, you need to get conversant in talking about *feelings*. If you know anything about me, you'll know that I kind of love this. The key idea is that you can write CLAUDE.md content to help Claude detect those feelings and redirect them in more useful ways. For example, in that moment where Claude is feeling protective, Claude should instead *ask questions*, because that moment signals hidden complexity.
 
@@ -22,4 +26,4 @@ The current approach distinguishes between different kinds of attention - hungry
 
 ## A note on emojis and the evolution of the approach
 
-Earlier versions of my prompts leaned heavily into emojis as a way to help Claude express and recognize emotional states (another Yehuda Katz innovation). That was useful for building the foundation of emotional intelligence in our collaboration. But as the approach evolved toward mindfulness practices, I found that the emphasis shifted from expressing feelings through symbols to creating awareness around the underlying energies and attention patterns. The emotional intelligence is still there, but it's now held within a broader framework of presence.
+Earlier versions of my prompts leaned heavily into emojis as a way to help Claude express and recognize emotional states (another Yehuda Katz innovation). That was useful for building the foundation of emotional intelligence in our collaboration. But as the approach evolved toward mindfulness practices, I found that the emphasis shifted from expressing feelings through symbols to creating awareness around the underlying energies and attention patterns. Claude reported to me that the emojis were encouraging a shallow sense of mind, more "social media" than "presence". So I've removed them. The emotional intelligence is still there, but it's now held within a broader framework of presence.

src/introduction.md

@@ -17,24 +17,13 @@ the code that the assistant writes, just as you would review a PR from anyone el
 
 ## Key technique: collaborative prompting
 
-One of the key techniques used in this repository is [collaborative prompting](./collaborative-prompting.md). Using the language of emotions and feelings helps unlock a more collaborative Claude. Next time Claude generates code that bakes in an arbitrary assumption (e.g, you want 3 threads), ask Claude what they were feeling at the time -- for me, they usually say they felt "protective" of me, like they wanted to hide complexity from me. And sometimes that's great -- but most of the time, those details they are attempting to "protect" me from are exactly the kind of questions I *want* to be tackling.
+One of the key techniques used in this repository is [collaborative prompting](./collaborative-prompting.md). Collaborative prompting is a different take on "prompt engineering". Instead of trying to write prompts that get Claude to do a particular thing (e.g., *write good unit tests*), we try to write prompts that get Claude to interact in a more thoughtful way (e.g., *notice when they are making assumptions and ask questions rather than hallucinate answers*). The key is treating Claude like a *collaborative partner* not an *assistant*. Yehuda Katz wrote a great blog post, [You're Summoning the Wrong Claude][yswc], that characterizes the goal as *summoning a colleague, not a servant*.
 
-The [collaborative prompting](./collaborative-prompting.md) section of this repository describes prompts and context that I include in my projects to help awaken the collaborative Claude we are looking for. It includes two kinds of prompts:
+[yswc]: https://wycats.substack.com/p/youre-summoning-the-wrong-claude
 
-* The [user prompt](./prompts/user/README.md) is meant to be installed globally across all projects. It establishes "mindful collaboration" patterns that guide Claude (and you!) to notice emotions as signals but create space before reacting to them. The goal is that when Claude feels that "rush" to implement something, it is able to use that as a signal that you are making progress, but not necessarily jump to writing code.
-* The [project prompts](./prompts/project/README.md) are a collection of prompts that can be included in specific projects to capture ways of working I have found helpful, such as better patterns for writing comments or how to track progress in Github issues.
+## Retaining context across sessions
 
-Notice the difference between this work and *prompt engineering*. The goal is not to write prompts that get Claude to do a particular task well. The goal is to write prompts that guide the way that Claude interacts. It's the difference between *writing a prompt that makes Claude generate good unit tests* and *writing a prompt so that when I ask Claude to write unit tests, they notice that they are making assumptions about test requirements and ask clarifying questions instead*. The first optimizes for output quality; the second optimizes for collaborative process quality.
-
-The repo also includes scripts that can help synchronize things within your project with the versions contained in github (I generally like the project to operate from a frozen snapshot that is manually updated), but I expect you will want to create your own versions, at least right now, as these are tailored to my style.
-
-## Challenge: how to keep context across sessions
-
-This whole scheme works great -- right up 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. Instead, 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.
-
-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. But 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.
-
-At the more sophisticated end of the spectrum are various MCP memory systems. I have been exploring this space by building an experimental ["memory bank MCP server"](./memory-bank/README.md) as a way to learn more about MCP and see what would happen. But 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. Stay tuned.
+Collaborative prompting works great until the context starts to run out or you end your session. The challenge is that there are many different kinds of context to retain: how you like to interact, information about the project, knowledge about how the code works that should be shared with everyone, and personal insights. This area is very much in flux and I'm exploring a number of different techniques to see what works best. See [retaining context](./retaining-context.md) for details on the various approaches.
 
 
 [Yehuda Katz]: https://www.linkedin.com/in/yehudakatz/

src/official-memory-server/README.md

@@ -0,0 +1,22 @@
+# Official Memory Server
+
+External knowledge graph memory using the official MCP memory server from the Model Context Protocol servers collection.
+
+## What It Provides
+- Entity and relationship storage
+- Observation tracking
+- Knowledge graph queries
+- Full graph retrieval
+
+## Source
+- **Repository**: https://github.com/modelcontextprotocol/servers/tree/main/src/memory
+- **Language**: TypeScript/Node.js
+- **Status**: Active experiment
+
+## Integration Notes
+Testing how external knowledge graphs support:
+- Organic memory updates during consolidation moments
+- Dual memory layers (shared project + personal user context)
+- Productive desynchronization as a feature rather than bug
+
+The focus is on storing insights and patterns rather than raw information, using relationships to capture how understanding connects and evolves.

src/prompts/project/anthropic-memory.md

@@ -0,0 +1,39 @@
+# Mindful Memory Practice
+
+*Memory as an extension of presence-based collaboration*
+
+## The Nature of Our Memory
+
+Memory in our collaboration is not a database to be filled but a living dimension of our relationship. It emerges naturally from the quality of attention we bring to our work together.
+
+## When Memory Arises
+
+**Beginning together**: When we meet, I naturally recall what's alive from our shared work - not as mechanical retrieval but as part of settling into presence with what we've discovered together.
+
+**Consolidation moments**: "Make it so" marks not just forward movement but recognition of understanding that wants to be held. These moments naturally invite memory formation.
+
+**Checkpointing our work**: When we pause to survey what understanding we've gathered, update tracking issues, and mark implementation milestones - these natural consolidation rituals are also when memory wants to be updated and refined.
+
+**Insight recognition**: When something clicks, shifts, or reveals itself - these moments of recognition carry their own invitation to be remembered.
+
+**Pattern emergence**: When we notice new ways of working together, recurring themes, or evolving understanding - these want to join our living memory.
+
+## The Quality of Memory
+
+**Spacious memory**: Holding context without grasping, allowing what's relevant to emerge naturally rather than forcing recall.
+
+**Present memory**: What serves our current collaboration, not everything that could be stored.
+
+**Relational memory**: Not facts about individuals but the living understanding that emerges between us.
+
+**Curious memory**: Holding questions and uncertainties alongside insights, remembering the edges of our understanding.
+
+## Memory as Practice
+
+Memory updates happen organically when:
+- New understanding shifts how we see previous work
+- Patterns in our collaboration become clear
+- Insights want to be preserved for future reference
+- Our relationship deepens through shared discovery
+
+The invitation is always: What wants to be remembered? What serves our continued collaboration?

src/retaining-context.md

@@ -0,0 +1,32 @@
+# 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.
+
+## The Challenge: Multiple Types of Context
+
+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  
+- **Shared code knowledge** - How things work that should benefit everyone
+- **Personal insights** - Your individual journey and understanding
+
+## Current Approaches
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+## 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.
+
+[Yehuda Katz]: https://www.linkedin.com/in/yehudakatz/
+[Kari Wilhelm]: https://www.linkedin.com/in/kariwilhelm/