amcs/llm/plan.md

Avalon Memory Crystal Server (amcs)

Implementation Plan Audit — Current State and Remaining Work

This file started as the original LiteLLM-first implementation plan for the Go rewrite. The repo has moved well past that starting point, so this document now serves as an audit of what the plan covered, what is already done, and what still appears to be outstanding.

For current usage and setup, prefer README.md. For the specific embedding-backfill follow-up work, see llm/todo.md.

---

Status summary

Original v1 plan: substantially complete

The original core plan is no longer a future roadmap item. The repo already contains the major v1 pieces that this document proposed, including:

• YAML-driven config and startup
• Postgres-backed storage with pgvector
• LiteLLM as the primary hosted AI path
• direct OpenRouter support
• MCP over Streamable HTTP
• authenticated MCP endpoints
• core thought tools
• project/context tools
• link traversal tools
• health/readiness endpoints
• file storage tools
• metadata retry and reparse maintenance tools
• embedding backfill and text-search fallback

In practice, the project has also grown beyond the original v1 scope with additional domains and tooling such as:

• stored files and binary resources
• agent skills and guardrails
• chat history tools
• household / maintenance / calendar / meal / CRM tools
• OAuth client-credentials support
• Ollama support
• tool discovery and persistent tool annotations

---

What from the original plan is already implemented

Core server and platform work

Implemented in the current repo:

• Streamable HTTP MCP server
• API-key auth middleware
• OAuth token flow support
• YAML config loader and validation
• Postgres connection verification and startup checks
• structured logging
• health and readiness endpoints
• version reporting

Original thought and project toolset

Implemented in the current repo:

• capture_thought
• search_thoughts
• list_thoughts
• thought_stats
• get_thought
• update_thought
• delete_thought
• archive_thought
• create_project
• list_projects
• get_project_context
• set_active_project
• get_active_project
• summarize_thoughts
• recall_context
• link_thoughts
• related_thoughts

Provider and retrieval work

Implemented in the current repo:

• LiteLLM provider path
• direct OpenRouter path
• Ollama path
• semantic search against model-specific embeddings
• full-text search fallback when embeddings do not exist for the active model in scope
• embedding backfill support
• metadata retry support for pending/failed extractions
• metadata reparse support

Scope that has gone beyond the original plan

Additional capabilities now present in the repo:

• file upload/save/load/list
• agent skills and guardrails plus project linking
• tool discovery via describe_tools
• persistent usage notes via annotate_tool
• chat history tools
• domain-specific household / maintenance / calendar / meals / CRM tooling

---

Remaining deferred features from the original plan

These still appear to be legitimate future work items.

1. Slack ingestion

Still outstanding.

2. Webhook ingestion

Still outstanding.

3. Per-user tenancy

Still outstanding.

4. Admin UI

Still outstanding.

5. Multi-provider routing policy inside the app

Still outstanding.

---

Deferred items from the original plan that are no longer accurate as open work

Async metadata extraction

This was originally listed as deferred, but the repo now already behaves much closer to the deferred target than this document suggests:

• capture can persist the thought even when metadata extraction fails or times out
• pending/failed metadata can be retried later
• metadata retry can run automatically in the background

That does not necessarily mean the design is final, but it is no longer accurate to treat async metadata handling as untouched future work.

Background enrichment jobs

The exact phrase from the original plan is still broad, but the repo already includes background-style maintenance flows such as:

• embedding backfill
• metadata retry
• metadata reparse support

So this plan should not be read as if AMCS has no background maintenance/enrichment machinery at all.

---

Notes for maintainers

When using this file for planning, treat it as historical context plus a high-level gap list.

Do not use the original milestone sections below as a literal roadmap. They describe the early intended build order, not the present state of the repo.

If a fresh roadmap is needed, create a new planning document based on the current codebase rather than continuing to extend the original greenfield plan.

---

Historical note

The rest of the original implementation-plan content was intentionally removed from this file during the audit cleanup because it described a mostly pre-implementation future state and was drifting away from the actual repository.

If needed, recover the older version from git history.