feat(files): introduce upload_file tool for staging files and enhance save_file documentation

llm/memory.md

@@ -32,9 +32,10 @@ At the start of every project session, after setting the active project:
 - Use project memory for code decisions, architecture, TODOs, debugging findings, and context specific to the current repo or workstream.
 - Before substantial work, always retrieve context with `get_project_context` or `recall_context` so prior decisions inform your approach.
 - Save durable project facts with `capture_thought` after completing meaningful work.
-- Use `save_file` for project assets the memory should retain, such as screenshots, PDFs, audio notes, and other documents.
-- If the goal is to retain the artifact itself, use `save_file` directly instead of first reading, transcribing, or summarizing the file contents.
-- When calling `save_file`, prefer `content_uri` over `content_base64` for binary files that were uploaded via HTTP — pass the `amcs://files/{id}` URI returned by the upload instead of re-encoding the bytes as base64.
+- Use `save_file` or `upload_file` for project assets the memory should retain, such as screenshots, PDFs, audio notes, and other documents.
+- If the goal is to retain the artifact itself, store the file directly instead of first reading, transcribing, or summarizing its contents.
+- For binary files or files larger than 10 MB, call `upload_file` with `content_path` (absolute server-side path) first to get an `amcs://files/{id}` URI, then pass that URI to `save_file` as `content_uri` to link it to a thought. This avoids base64 encoding entirely.
+- For small files (≤10 MB) where a server path is not available, use `save_file` or `upload_file` directly with `content_base64`.
 - Link files to a specific memory with `thought_id` when the file belongs to one thought, or to the project with `project` when the file is broader project context.
 - Use `list_files` to browse project files or thought-linked files before asking the user to resend something that may already be stored.
 - Use `load_file` when you need the actual stored file contents back. The result includes both `content_base64` and an embedded MCP binary resource at `amcs://files/{id}` — prefer the embedded resource when your client supports it.
@@ -55,7 +56,7 @@ At the start of every project session, after setting the active project:
 - Prefer concise summaries.
 - Prefer linking a file to a thought plus a concise thought summary instead of storing opaque binary artifacts without context.
 - Do not read a file just to make it storable; store the file directly and read it only when the file contents are needed for reasoning.
-- Do not base64-encode a file to pass it to `save_file` if an `amcs://files/{id}` URI is already available from a prior HTTP upload.
+- Do not base64-encode a file to pass it to `save_file` if an `amcs://files/{id}` URI is already available from a prior `upload_file` or HTTP upload.
 - When saving, choose the narrowest correct scope: project if project-specific, global if not.
 
 ## Skills and Guardrails
@@ -68,4 +69,4 @@ At the start of every project session, after setting the active project:
 
 ## Short Operational Form
 
-Use AMCS memory in project scope when the current work matches a known project. If no clear project matches, global notebook memory is allowed for non-project-specific information. At the start of every project session call `list_project_skills` and `list_project_guardrails` and apply what is returned; only create new skills or guardrails if none exist. Store durable notes with `capture_thought`, store supporting binary artifacts with `save_file`, prefer saving a file directly when the artifact itself is what matters, browse stored files with `list_files`, and load them with `load_file` only when their contents are needed. When saving a file uploaded via HTTP, pass `content_uri: "amcs://files/{id}"` instead of re-encoding it as base64. Stored files can also be read as raw binary via MCP resources at `amcs://files/{id}`. Never store project-specific memory globally when a matching project exists, and never store memory in the wrong project. If project matching is ambiguous, ask the user.
+Use AMCS memory in project scope when the current work matches a known project. If no clear project matches, global notebook memory is allowed for non-project-specific information. At the start of every project session call `list_project_skills` and `list_project_guardrails` and apply what is returned; only create new skills or guardrails if none exist. Store durable notes with `capture_thought`. For binary files or files larger than 10 MB, call `upload_file` with `content_path` to stage the file and get an `amcs://files/{id}` URI, then pass that URI to `save_file` as `content_uri` to link it to a thought. For small files, use `save_file` or `upload_file` with `content_base64` directly. Browse stored files with `list_files`, and load them with `load_file` only when their contents are needed. Stored files can also be read as raw binary via MCP resources at `amcs://files/{id}`. Never store project-specific memory globally when a matching project exists, and never store memory in the wrong project. If project matching is ambiguous, ask the user.