Add README and initial project plan documentation

README.md

@@ -1,3 +1,52 @@
-# amcs
+# Avalon Memory Crystal Server  (amcs)
 
-Avalon Memory Crystal Server
+![Avalon Memory Crystal](assets/avelonmemorycrystal.jpg)
+
+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.
+
+## What it does
+
+- **Capture** thoughts with automatic embedding and metadata extraction
+- **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
+
+- Go — MCP server over Streamable HTTP
+- Postgres + pgvector — storage and vector search
+- LiteLLM — primary AI provider (embeddings + metadata extraction)
+- OpenRouter — default upstream behind LiteLLM
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `capture_thought` | Store a thought with embedding and metadata |
+| `search_thoughts` | Semantic similarity search |
+| `list_thoughts` | Filter thoughts by type, topic, person, date |
+| `thought_stats` | Counts and top topics/people |
+| `get_thought` | Retrieve a thought by ID |
+| `update_thought` | Patch content or metadata |
+| `delete_thought` | Hard delete |
+| `archive_thought` | Soft delete |
+| `create_project` | Register a named project |
+| `list_projects` | List projects with thought counts |
+| `get_project_context` | Recent + semantic context for a project |
+| `set_active_project` | Set session project scope |
+| `get_active_project` | Get current session project |
+| `summarize_thoughts` | LLM prose summary over a filtered set |
+| `recall_context` | Semantic + recency context block for injection |
+| `link_thoughts` | Create a typed relationship between thoughts |
+| `related_thoughts` | Explicit links + semantic neighbours |
+
+## Configuration
+
+Config is YAML-driven. Copy `configs/config.example.yaml` and set:
+
+- `database.url` — Postgres connection string
+- `auth.keys` — API keys for MCP endpoint access
+- `ai.litellm.base_url` and `ai.litellm.api_key` — LiteLLM proxy
+
+See `llm/plan.md` for full architecture and implementation plan.