README.md

@@ -1,24 +1,18 @@
-# Avalon Memory Crystal Server  (amcs)
+# AMCS Directory
 
-![Avalon Memory Crystal](assets/avelonmemorycrystal.jpg)
+This is the AMCS (Advanced Module Control System) directory.
 
-A Go MCP server for capturing and retrieving thoughts, memory, and project context. Exposes tools over Streamable HTTP, backed by Postgres with pgvector for semantic search.
+## Purpose
 
-## What it does
+The AMCS directory is used to store configuration and code for the Advanced Module Control System, which handles...
 
-- **Capture** thoughts with automatic embedding and metadata extraction
+## Structure
-- **Search** thoughts semantically via vector similarity
-- **Organise** thoughts into projects and retrieve full project context
-- **Summarise** and recall memory across topics and time windows
-- **Link** related thoughts and traverse relationships
 
-## Stack
+- `configs/` - Configuration files
+- `scripts/` - Scripts for managing the system
+- `assets/` - Asset files
 
-- Go — MCP server over Streamable HTTP
+## Next Steps
-- Postgres + pgvector — storage and vector search
-- LiteLLM — primary hosted AI provider (embeddings + metadata extraction)
-- OpenRouter — default upstream behind LiteLLM
-- Ollama — supported local or self-hosted OpenAI-compatible provider
 
 ## Tools
 

llm/learnings_schema.md

@@ -0,0 +1,77 @@
+# Structured Learnings Schema (v1)
+
+## Data Model
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **ID** | string | Stable learning identifier |
+| **Category** | enum | `correction`, `insight`, `knowledge_gap`, `best_practice` |
+| **Area** | enum | `frontend`, `backend`, `infra`, `tests`, `docs`, `config`, `other` |
+| **Status** | enum | `pending`, `in_progress`, `resolved`, `wont_f` |
+| **Priority** | string | e.g., `low`, `medium`, `high` |
+| **Summary** | string | Brief description |
+| **Details** | string | Full description / context |
+| **ProjectID** | string (optional) | Reference to a project |
+| **ThoughtID** | string (optional) | Reference to a thought |
+| **SkillID** | string (optional) | Reference to a skill |
+| **CreatedAt** | timestamp | Creation timestamp |
+| **UpdatedAt** | timestamp | Last update timestamp |
+
+## Suggested SQL Definition
+
+```sql
+CREATE TABLE learnings (
+    id UUID PRIMARY KEY,
+    category TEXT NOT NULL,
+    area TEXT NOT NULL,
+    status TEXT NOT NULL,
+    priority TEXT,
+    summary TEXT,
+    details TEXT,
+    project_id UUID,
+    thought_id UUID,
+    skill_id UUID,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+```
+
+## Tool Surface (MCP)
+
+- `create_learning` – insert a new learning record  
+- `list_learnings` – query with optional filters (category, area, status, project, etc.)  
+- `get_learning` – retrieve a single learning by ID  
+- `update_learning` – modify fields (e.g., status, priority) and/or links  
+
+## Enums (Go)
+
+```go
+type LearningCategory string
+const (
+    LearningCategoryCorrection LearningCategory = "correction"
+    LearningCategoryInsight    LearningCategory = "insight"
+    LearningCategoryKnowledgeGap LearningCategory = "knowledge_gap"
+    LearningCategoryBestPractice LearningCategory = "best_practice"
+)
+
+type LearningArea string
+const (
+    LearningAreaFrontend      LearningArea = "frontend"
+    LearningAreaBackend       LearningArea = "backend"
+    LearningAreaInfra         LearningArea = "infra"
+    LearningAreaTests         LearningArea = "tests"
+    LearningAreaDocs          LearningArea = "docs"
+    LearningAreaConfig        LearningArea = "config"
+    LearningAreaOther         LearningArea = "other"
+)
+
+type LearningStatus string
+const (
+    LearningStatusPending      LearningStatus = "pending"
+    LearningStatusInProgress   LearningStatus = "in_progress"
+    LearningStatusResolved     LearningStatus = "resolved"
+    LearningStatusWontF        LearningStatus = "wont_f"
+)
+```
+
+Let me know if this alignment works or if you’d like any adjustments before I proceed with the implementation.

llm/sample_learning.json

@@ -0,0 +1,14 @@
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "category": "insight",
+  "area": "frontend",
+  "status": "pending",
+  "priority": "high",
+  "summary": "Understanding React hooks lifecycle",
+  "details": "React hooks provide a way to use state and other React features without writing a class. This learning note captures key insights about hooks lifecycle and common pitfalls.",
+  "project_id": "proj-001",
+  "thought_id": "th-001",
+  "skill_id": "skill-001",
+  "created_at": "2026-04-05T19:30:00Z",
+  "updated_at": "2026-04-05T19:30:00Z"
+}

llm/structured-learnings/README.md

@@ -0,0 +1,7 @@
+# Structured Learnings
+
+This directory is intended to hold structured learning modules and resources.
+
+---
+
+*Add your learning materials here.*