Updated proxy contract (Release v0.6.1)

Author: daverage

examples/Crush.md

@@ -1,58 +1,50 @@
 # tinyMem Crush/Rush Integration Guide
 
-[Crush](https://github.com/charmbracelet/crush) (and its CLI `rush`) supports the **Model Context Protocol (MCP)**, making integration with tinyMem native and powerful.
+[Crush](https://github.com/charmbracelet/crush) (and its CLI `rush`) supports both **Model Context Protocol (MCP)** and standard **OpenAI-compatible APIs**, giving you two flexible ways to integrate with tinyMem.
 
-## Configuration
+## Option A: MCP Mode (Recommended)
+
+This mode allows Rush to natively use tinyMem's tools (like `memory_query`, `memory_write`, `memory_health`) to actively manage context during your chat.
+
+### 1. Configuration
 
 Crush looks for a configuration file at `.crush.json` (project local) or `~/.config/crush/crush.json` (global).
 
-1.  **Install tinyMem** and ensure it's in your PATH.
-2.  **Create/Edit `.crush.json`:**
-
-    ```json
-    {
-      "mcp": {
-        "tinymem": {
-          "type": "stdio",
-          "command": "tinymem",
-          "args": ["mcp"],
-          "timeout": 120,
-          "env": {
-            "TINYMEM_METRICS_ENABLED": "true"
-          }
-        }
+**Create/Edit `.crush.json`:**
+
+```json
+{
+  "mcp": {
+    "tinymem": {
+      "type": "stdio",
+      "command": "tinymem",
+      "args": ["mcp"],
+      "timeout": 120,
+      "env": {
+        "TINYMEM_METRICS_ENABLED": "true"
       }
     }
-    ```
+  }
+}
+```
 
-    *If `tinymem` is not in PATH, replace `"command": "tinymem"` with `"command": "/absolute/path/to/tinymem"`.*
+*If `tinymem` is not in PATH, replace `"command": "tinymem"` with `"command": "/absolute/path/to/tinymem"`.*
 
-## Usage
+### 2. Usage (MCP)
 
 Start Rush:
 ```bash
 rush
 ```
 
-### Querying Memory
-You can ask Rush natural language questions about the project:
-> "What decisions did we make about the API structure?"
+Rush will now have access to tinyMem tools:
+-   **Querying:** "What decisions did we make about the API structure?" (Rush calls `memory_query`)
+-   **Writing:** "Remember that we decided to use Postgres for production." (Rush calls `memory_write`)
+-   **Health:** "Check if the memory system is working." (Rush calls `memory_health`)
 
-Rush will automatically call `memory_query` to fetch context before answering.
+### 3. Advanced MCP Config
 
-### Writing Memory
-> "Remember that we decided to use Postgres for production."
-
-Rush will call `memory_write` to store this decision.
-
-### Health Check
-> "Check if the memory system is working."
-
-Rush will call `memory_health`.
-
-## Advanced Crush Config
-
-You can tune the integration in `.crush.json`:
+You can tune the MCP integration in `.crush.json`:
 
 ```json
 {
@@ -65,18 +57,102 @@ You can tune the integration in `.crush.json`:
         "TINYMEM_LOG_LEVEL": "debug",
         "TINYMEM_RECALL_MAX_ITEMS": "20"
       },
-      "disabled_tools": [] // You can explicitly disable tools if needed
+      "disabled_tools": []
     }
   },
   "system_prompt_suffix": "\n\nUse tinyMem to check context before answering code questions."
 }
 ```
 
+---
+
+## Option B: Proxy Mode
+
+Use this mode if you want tinyMem to act as a transparent "middle-man," automatically injecting relevant memory context into every prompt before it reaches your LLM.
+
+### 1. Configure tinyMem
+
+Create a `config.toml` file (e.g., in your project root or home directory) to tell tinyMem where your actual LLM is running (e.g., Ollama, LM Studio, vLLM).
+
+```toml
+[agent]
+contract = 'small'
+
+[proxy]
+port = 8080
+base_url = "http://127.0.0.1:1234" # Your actual LLM backend (e.g., LM Studio, Ollama)
+
+[llm]
+model = "unsloth/rnj-1-instruct" # The model name your backend expects
+timeout = 5000
+
+[recall]
+max_items = 10
+
+[cove]
+enabled = true
+confidence_threshold = 0.6
+
+[logging]
+level = "info"
+file = "tinymem.log"
+```
+
+### 2. Start tinyMem Proxy
+
+Open a terminal and run:
+
+```bash
+tinymem proxy
+```
+*You should see logs indicating the proxy is listening on port 8080.*
+
+### 3. Configure Crush
+
+Edit your `.crush.json` to treat tinyMem as an OpenAI-compatible provider.
+
+```json
+{
+  "providers": {
+    "Ollama": {
+      "name": "Ollama",
+      "base_url": "http://localhost:8080/v1",
+      "type": "openai-compat",
+      "models": [
+        {
+          "name": "rnj",
+          "id": "unsloth/rnj-1-instruct",
+          "context_window": 256000,
+          "default_max_tokens": 20000
+        }
+      ]
+    }
+  }
+}
+```
+
+* **`base_url`**: Must point to tinyMem (`http://localhost:8080/v1`).
+* **`id`**: Should match the model name configured in `config.toml` (or be compatible with your backend).
+
+### 4. Usage (Proxy)
+
+Start Rush:
+```bash
+rush
+```
+
+In this mode, interaction is implicit:
+-   **Context Injection:** When you ask a question, tinyMem automatically searches its database and prepends relevant memories to your prompt.
+-   **Transparency:** Crush thinks it's talking directly to the LLM, but tinyMem is enriching the conversation in the background.
+
+---
+
 ## Configuration Reference
 
 For full configuration options, see [Configuration.md](Configuration.md).
 
 ## Troubleshooting
 
--   **Tools Not Available:** Check `rush --version` to ensure you have a version with MCP support.
--   **Execution Errors:** Run `rush` with debug flags or check `.tinyMem/logs/` to see if tinyMem is crashing or erroring.
+-   **Tools Not Available (MCP):** Check `rush --version` to ensure you have a version with MCP support.
+-   **Connection Refused (Proxy):** Ensure `tinymem proxy` is running and the port matches your `.crush.json` configuration.
+-   **Logs:** Check `.tinyMem/logs/` or the terminal where you ran `tinymem proxy` to see if requests are being processed.

internal/memory/contract.go

@@ -49,6 +49,9 @@ func EnsureProjectContracts(projectRoot string, contractType ContractType) error
 	if err := os.MkdirAll(agentsDir, 0755); err != nil {
 		return fmt.Errorf("error creating directory %s: %w", agentsDir, err)
 	}
+	if err := ensureAgentContractFiles(projectRoot); err != nil {
+		return fmt.Errorf("error ensuring agent contract files: %w", err)
+	}
 
 	files := []string{"AGENTS.md", "QWEN.md", "GEMINI.md", "CLAUDE.md", "CODEX.md"}
 	locations := []string{projectRoot, agentsDir}
@@ -80,10 +83,6 @@ func EnsureProjectContracts(projectRoot string, contractType ContractType) error
 		}
 	}
 
-	if err := updateReadme(projectRoot, contractType); err != nil {
-		return fmt.Errorf("error updating README.md: %w", err)
-	}
-
 	fmt.Println("Agent contracts synchronized.")
 	return nil
 }
@@ -191,6 +190,31 @@ func createFileWithContract(filename, contractContent string) error {
 	return nil
 }
 
+func ensureAgentContractFiles(projectRoot string) error {
+	agentsDir := filepath.Join(projectRoot, "docs", "agents")
+	contractTypes := []ContractType{ContractTypeLarge, ContractTypeSmall}
+	for _, cType := range contractTypes {
+		contractPath := filepath.Join(agentsDir, cType.fileName())
+		if _, err := os.Stat(contractPath); err == nil {
+			continue
+		} else if !os.IsNotExist(err) {
+			return fmt.Errorf("error checking %s: %w", contractPath, err)
+		}
+
+		fmt.Printf("Downloading missing %s contract to %s...\n", cType, contractPath)
+		content, err := getContractContent(projectRoot, cType)
+		if err != nil {
+			return fmt.Errorf("error fetching %s contract: %w", cType, err)
+		}
+
+		if err := createFileWithContract(contractPath, content); err != nil {
+			return fmt.Errorf("error creating %s: %w", contractPath, err)
+		}
+	}
+
+	return nil
+}
+
 func updateReadme(projectRoot string, contractType ContractType) error {
 	readmePath := filepath.Join(projectRoot, "README.md")
 	content, err := os.ReadFile(readmePath)

internal/version/version.go

@@ -2,4 +2,4 @@ package version
 
 // Version is the current version of tinyMem
 // This can be overridden at build time using -ldflags "-X github.com/daverage/tinymem/internal/version.Version=vX.Y.Z"
-var Version = "v0.6.0"
+var Version = "v0.6.1"