Implement Phase 1: Journal MCP Server JSON prototype

Complete implementation of all 5 MCP tools with comprehensive testing:

Core features:
- journal_write: Add entries and update overviews
- journal_read: Read sections with optional entry inclusion
- journal_search: Dual-dimension semantic search with temporal salience
- journal_toc: Navigate hierarchical journal structure
- journal_list_entries: Browse entries with pagination

Technical implementation:
- Python project with uv package manager
- JSON storage backend with atomic saves and nested sections
- Sentence-transformers for semantic embeddings
- Full type annotations and mypy compliance
- Comprehensive test suite (6/6 tests passing)
- CLI with configurable --data-file parameter

This validates the journal server interface design and provides
foundation for Phase 2 refinement and eventual git migration.

Closes Phase 1 deliverables in tracking issue #9.

Author: nikomatsakis

journal-mcp-server/.python-version

@@ -0,0 +1 @@
+3.11

journal-mcp-server/README.md

@@ -2,23 +2,106 @@
 
 A memory system that emerges from collaborative understanding, reimagining AI memory as an organic, reflective practice rather than mechanical storage.
 
+## Phase 1: JSON Prototype ✅
+
+The JSON prototype is now complete with all core functionality:
+
+- **5 MCP Tools**: `journal_read`, `journal_write`, `journal_search`, `journal_toc`, `journal_list_entries`
+- **Dual-dimension search**: Work context + content matching with temporal salience
+- **Configurable storage**: `--data-file` argument for custom JSON locations
+- **Full type checking**: mypy compliance with comprehensive test coverage
+
 ## Quick Start
 
-*Implementation coming soon - currently in design phase*
+### Installation
+
+```bash
+# Install in development mode
+uv pip install -e .
+
+# Run with default data file (./journal.json)
+uv run journal-server
+
+# Run with custom data file
+uv run journal-server --data-file ~/my-journal.json
+```
+
+### Testing
+
+```bash
+# Run all tests
+uv run pytest tests/ -v
+
+# Run type checking
+uv run mypy src/journal_server/ --ignore-missing-imports
+```
+
+## MCP Tools
+
+### journal_write
+Add entries and optionally update section overviews:
+```json
+{
+  "path": "project-alpha",
+  "entry": "Implemented user authentication with JWT tokens",
+  "work_context": "authentication development",
+  "overview": "Building secure user management system"
+}
+```
+
+### journal_read
+Read section overviews and recent entries:
+```json
+{
+  "path": "project-alpha",
+  "include_entries": true,
+  "max_entries": 5
+}
+```
+
+### journal_search
+Semantic search with dual-dimension matching:
+```json
+{
+  "work_context": "authentication development",
+  "content": "JWT tokens",
+  "salience_threshold": 0.5
+}
+```
+
+### journal_toc
+Navigate journal structure:
+```json
+{
+  "max_depth": 3
+}
+```
+
+### journal_list_entries
+Browse entries with pagination:
+```json
+{
+  "path": "project-alpha",
+  "limit": 10,
+  "offset": 0
+}
+```
+
+## Architecture
+
+**Core concept**: Git-centric design where journal sections are markdown files with current understanding as file contents and incremental entries stored as git commit messages.
+
+**Current implementation**: JSON prototype that validates the interface before migrating to git backend.
+
+**Tree structure**: Hierarchical organization with overviews (current synthesis), entries (chronological journey), and subsections that emerge naturally.
 
 ## Documentation
 
 For the full concept, design, and architecture details, see the [mdBook documentation](../src/journal-mcp-server/).
 
 ## Development Status
 
-Track implementation progress in the [GitHub tracking issue](https://github.com/nikomat/socratic-shell/issues) - look for "Journal MCP Server Implementation".
-
-## Core Concept
-
-The journal server uses git as both storage engine and identifier system:
-- **File contents**: Current understanding (overview)
-- **Commit messages**: Incremental journey (journal entries)  
-- **Git history**: Complete collaborative record
+Track implementation progress in [GitHub issue #9](https://github.com/socratic-shell/socratic-shell/issues/9).
 
-This creates a memory system that captures both our current understanding and the collaborative journey that led there, aligning with natural patterns of exploration → synthesis → new exploration.
+**Phase 1 Complete**: JSON prototype with all 5 MCP tools working  
+**Next**: Phase 2 interface refinement and real-world testing

journal-mcp-server/main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from journal-server!")
+
+
+if __name__ == "__main__":
+    main()

journal-mcp-server/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "journal-server"
+version = "0.1.0"
+description = "A memory system that emerges from collaborative understanding"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.12.1",
+    "pydantic>=2.11.7",
+    "sentence-transformers>=5.0.0",
+]
+
+[project.scripts]
+journal-server = "journal_server.cli:main"
+
+[dependency-groups]
+dev = [
+    "black>=25.1.0",
+    "isort>=6.0.1",
+    "mypy>=1.17.0",
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.1.0",
+]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+# Relax strict mode for MCP integration
+strict = false
+
+[tool.black]
+line-length = 88
+target-version = ['py311']
+
+[tool.isort]
+profile = "black"
+line_length = 88

journal-mcp-server/src/journal_server/__init__.py

@@ -0,0 +1,3 @@
+"""Journal Server - A memory system that emerges from collaborative understanding."""
+
+__version__ = "0.1.0"

journal-mcp-server/src/journal_server/cli.py

@@ -0,0 +1,30 @@
+"""CLI entry point for the journal server."""
+
+import argparse
+import asyncio
+from pathlib import Path
+
+from .server import JournalServer
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Journal MCP Server - A memory system that emerges from collaborative understanding"
+    )
+    parser.add_argument(
+        "--data-file",
+        type=Path,
+        default=Path("./journal.json"),
+        help="Path to the JSON data file (default: ./journal.json)",
+    )
+    
+    args = parser.parse_args()
+    
+    # Create and run the server
+    server = JournalServer(data_file=args.data_file)
+    asyncio.run(server.run())
+
+
+if __name__ == "__main__":
+    main()

journal-mcp-server/src/journal_server/search.py

@@ -0,0 +1,135 @@
+"""Semantic search implementation for journal entries."""
+
+import math
+from datetime import datetime, timedelta
+from typing import Any, List, Tuple, TYPE_CHECKING
+
+from sentence_transformers import SentenceTransformer
+
+from .types import Journal, JournalEntry, SearchResult
+
+if TYPE_CHECKING:
+    from .types import JournalSection
+
+
+class JournalSearcher:
+    """Semantic search for journal entries with dual-dimension matching."""
+    
+    def __init__(self) -> None:
+        # Use a lightweight model for embeddings
+        self.model = SentenceTransformer('all-MiniLM-L6-v2')
+    
+    def search(
+        self,
+        journal: Journal,
+        work_context: str,
+        content: str,
+        salience_threshold: float = 0.5,
+        max_results: int = 10,
+    ) -> List[SearchResult]:
+        """Search journal entries using dual-dimension matching."""
+        
+        # Generate embeddings for search queries
+        work_context_embedding = self.model.encode([work_context])[0]
+        content_embedding = self.model.encode([content])[0]
+        
+        results: List[SearchResult] = []
+        
+        # Search through all sections and entries
+        for section_path, section in journal.sections.items():
+            self._search_section(
+                section, section_path, work_context_embedding, content_embedding,
+                salience_threshold, results
+            )
+        
+        # Sort by combined score (descending)
+        results.sort(key=lambda r: r.combined_score, reverse=True)
+        
+        return results[:max_results]
+    
+    def _search_section(
+        self,
+        section: "JournalSection",
+        section_path: str,
+        work_context_embedding: Any,
+        content_embedding: Any,
+        salience_threshold: float,
+        results: List[SearchResult],
+    ) -> None:
+        """Recursively search a section and its subsections."""
+        
+        # Search entries in this section
+        for i, entry in enumerate(section.entries):
+            result = self._score_entry(
+                section_path, i, entry, work_context_embedding, content_embedding
+            )
+            
+            if result.combined_score >= salience_threshold:
+                results.append(result)
+        
+        # Search subsections
+        for subsection_name, subsection in section.subsections.items():
+            subsection_path = f"{section_path}/{subsection_name}"
+            self._search_section(
+                subsection, subsection_path, work_context_embedding, content_embedding,
+                salience_threshold, results
+            )
+    
+    def _score_entry(
+        self,
+        section_path: str,
+        entry_index: int,
+        entry: JournalEntry,
+        work_context_embedding: Any,
+        content_embedding: Any,
+    ) -> SearchResult:
+        """Score a single entry against the search criteria."""
+        
+        # Generate embeddings for the entry
+        entry_work_embedding = self.model.encode([entry.work_context])[0]
+        entry_content_embedding = self.model.encode([entry.content])[0]
+        
+        # Calculate cosine similarity scores
+        work_context_score = self._cosine_similarity(work_context_embedding, entry_work_embedding)
+        content_score = self._cosine_similarity(content_embedding, entry_content_embedding)
+        
+        # Calculate temporal salience (recent entries score higher)
+        temporal_score = self._calculate_temporal_score(entry.timestamp)
+        
+        # Combine scores (equal weight for now, could be tunable)
+        combined_score = (work_context_score + content_score) / 2 * temporal_score
+        
+        return SearchResult(
+            section_path=section_path,
+            entry_index=entry_index,
+            entry=entry,
+            work_context_score=work_context_score,
+            content_score=content_score,
+            combined_score=combined_score,
+            temporal_score=temporal_score,
+        )
+    
+    def _cosine_similarity(self, a: Any, b: Any) -> float:
+        """Calculate cosine similarity between two vectors."""
+        import numpy as np
+        
+        dot_product = np.dot(a, b)
+        norm_a = np.linalg.norm(a)
+        norm_b = np.linalg.norm(b)
+        
+        if norm_a == 0 or norm_b == 0:
+            return 0.0
+            
+        return float(dot_product / (norm_a * norm_b))
+    
+    def _calculate_temporal_score(self, timestamp: datetime) -> float:
+        """Calculate temporal salience score (recent entries score higher)."""
+        now = datetime.utcnow()
+        age = now - timestamp
+        
+        # Exponential decay with half-life of 30 days
+        half_life_days = 30
+        decay_factor = math.exp(-age.days * math.log(2) / half_life_days)
+        
+        # Ensure minimum score of 0.1 for very old entries
+        return max(0.1, decay_factor)