init and update (Release v0.5.3)

Author: daverage

README.md

@@ -197,7 +197,8 @@ The tinyMem CLI is your primary way to interact with the system from your termin
 | `run` | **Command Wrapper**| To run a script or tool (like `make` or `npm test`) while "reminding" it of project context. | `tinymem run make build` |
 | `proxy` / `mcp` | **Server Modes** | To start the "brain" that connects tinyMem to your IDE or AI client. | `tinymem mcp` |
 | `doctor` | **Diagnostics** | To fix the system if it stops working or has configuration issues. | `tinymem doctor` |
-| `addContract` | **Agent Setup** | To automatically configure your AI agents to use tinyMem properly. | `tinymem addContract` |
+| `init` | **Project Bootstrap** | Creates `.tinyMem`, writes the config, and installs the correct agent contracts for your model size. | `tinymem init` |
+| `update` | **Refresh** | Re-runs migrations and downloads whichever agent contract matches your configuration. | `tinymem update` |
 
 ### Writing Memories
 Think of writing memories as "tagging" reality for the AI.
@@ -298,12 +299,13 @@ When tinyMem is running in MCP mode, your AI agent (like Claude or Gemini) gains
 ### AI Agent Directives
 **CRITICAL**: If you are building an AI agent, you MUST include the appropriate directive in its system prompt to ensure it uses tinyMem correctly.
 
-**Quick Setup:** Run `tinymem addContract` to automatically create these files in your project.
+**Quick Setup:** Run `tinymem init` once to bootstrap `.tinyMem`, create config, and install the correct agent contract for your model size. Use `tinymem update` later to rerun migrations and refresh the contract (it will download the small or large version that your configuration points to).
 
 *   **Claude**: [`docs/agents/CLAUDE.md`](docs/agents/CLAUDE.md)
 *   **Gemini**: [`docs/agents/GEMINI.md`](docs/agents/GEMINI.md)
 *   **Qwen**: [`docs/agents/QWEN.md`](docs/agents/QWEN.md)
-*   **Other**: [`docs/agents/AGENT_CONTRACT.md`](docs/agents/AGENT_CONTRACT.md)
+*   **Other (Large LLMs)**: [`docs/agents/AGENT_CONTRACT.md`](docs/agents/AGENT_CONTRACT.md)
+*   **Other (Tiny LLMs)**: [`docs/agents/AGENT_CONTRACT_SMALL.md`](docs/agents/AGENT_CONTRACT_SMALL.md)
 
 ---
 

cmd/tinymem/main.go

@@ -1,6 +1,7 @@
 package main
 
 import (
+	"bufio"
 	"context"
 	"fmt"
 	"net"
@@ -13,15 +14,17 @@ import (
 
 	"github.com/daverage/tinymem/internal/analytics"
 	"github.com/daverage/tinymem/internal/app"
+	"github.com/daverage/tinymem/internal/config"
 	"github.com/daverage/tinymem/internal/cove"
+	"github.com/daverage/tinymem/internal/memory"
+	"github.com/daverage/tinymem/internal/storage"
 	"github.com/spf13/cobra"
 	"go.uber.org/zap"
 
 	"github.com/daverage/tinymem/internal/doctor"
 	"github.com/daverage/tinymem/internal/evidence"
 	"github.com/daverage/tinymem/internal/inject"
 	"github.com/daverage/tinymem/internal/logging"
-	"github.com/daverage/tinymem/internal/memory"
 	"github.com/daverage/tinymem/internal/recall"
 	"github.com/daverage/tinymem/internal/server/mcp"
 	"github.com/daverage/tinymem/internal/server/proxy"
@@ -44,7 +47,8 @@ func init() {
 	rootCmd.AddCommand(doctorCmd)
 	rootCmd.AddCommand(recentCmd)
 	rootCmd.AddCommand(queryCmd)
-	rootCmd.AddCommand(contractCmd)
+	rootCmd.AddCommand(initCmd)
+	rootCmd.AddCommand(updateCmd)
 	rootCmd.AddCommand(completionCmd)
 	rootCmd.AddCommand(dashboardCmd)
 	rootCmd.AddCommand(writeCmd)
@@ -591,16 +595,55 @@ func runWriteCmd(a *app.App, cmd *cobra.Command, args []string) {
 	}
 }
 
-var contractCmd = &cobra.Command{
-	Use:   "addContract",
-	Short: "Add the MANDATORY TINYMEM CONTROL PROTOCOL to agent markdown files",
+var initCmd = &cobra.Command{
+	Use:   "init",
+	Short: "Initialize tinyMem state (config, database, contract files)",
+}
+
+var updateCmd = &cobra.Command{
+	Use:   "update",
+	Short: "Update database schema and refresh agent contracts",
+}
+
+func runInitCmd(a *app.App, cmd *cobra.Command, args []string) {
+	projectRoot := a.Project.Path
+	fmt.Printf("Initializing tinyMem in %s\n", projectRoot)
+
+	defaultContract := memory.ParseContractType(a.Core.Config.AgentContract)
+	contractType := selectContractType(defaultContract)
+
+	if err := config.SaveAgentContractChoice(projectRoot, string(contractType)); err != nil {
+		a.Core.Logger.Error("Failed to persist agent contract choice", zap.Error(err))
+		fmt.Printf("❌ Unable to save agent contract choice: %v\n", err)
+		os.Exit(1)
+	}
+	a.Core.Config.AgentContract = string(contractType)
+
+	if err := memory.EnsureProjectContracts(projectRoot, contractType); err != nil {
+		a.Core.Logger.Error("Failed to initialize agent contracts", zap.Error(err))
+		fmt.Printf("❌ Contract initialization failed: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Println("tinyMem initialization complete.")
 }
 
-func runContractCmd(a *app.App, cmd *cobra.Command, args []string) {
-	if err := memory.AddContract(); err != nil {
-		a.Core.Logger.Error("Failed to add contract", zap.Error(err))
-		fmt.Printf("❌ Failed to add contract: %v\n", err)
+func runUpdateCmd(a *app.App, cmd *cobra.Command, args []string) {
+	fmt.Println("Running database migrations and refreshing contracts...")
+	if err := runMigrations(a.Core.Config); err != nil {
+		a.Core.Logger.Error("Failed to run migrations", zap.Error(err))
+		fmt.Printf("❌ Migration failed: %v\n", err)
+		os.Exit(1)
+	}
+
+	contractType := memory.ParseContractType(a.Core.Config.AgentContract)
+	if err := memory.EnsureProjectContracts(a.Project.Path, contractType); err != nil {
+		a.Core.Logger.Error("Failed to refresh contracts", zap.Error(err))
+		fmt.Printf("❌ Contract refresh failed: %v\n", err)
+		os.Exit(1)
 	}
+
+	fmt.Println("Update complete.")
 }
 
 var dashboardCmd = &cobra.Command{
@@ -659,6 +702,37 @@ func newAppRunner(a *app.App, runFunc func(*app.App, *cobra.Command, []string))
 	}
 }
 
+func runMigrations(cfg *config.Config) error {
+	db, err := storage.NewDB(cfg)
+	if err != nil {
+		return err
+	}
+	return db.Close()
+}
+
+func selectContractType(defaultType memory.ContractType) memory.ContractType {
+	reader := bufio.NewReader(os.Stdin)
+	fmt.Println("Which kind of LLM agent are you configuring?")
+	fmt.Println("  small - Claude CLI, Ollama, Qwen3 8B (tiny, instruction-tuned models)")
+	fmt.Println("  large - Claude 3, GPT-4.1 Turbo, Claude 3 Opus (default for bigger agents)")
+	fmt.Printf("Choose contract (small/large) [%s]: ", defaultType)
+
+	input, err := reader.ReadString('\n')
+	if err != nil {
+		fmt.Printf("\nInput error, defaulting to %s\n", defaultType)
+		return defaultType
+	}
+
+	input = strings.TrimSpace(input)
+	if input == "" {
+		return defaultType
+	}
+
+	selection := memory.ParseContractType(input)
+	fmt.Printf("Selected %s agent contract\n", selection)
+	return selection
+}
+
 func main() {
 	appInstance, err := app.NewApp()
 	if err != nil {
@@ -681,7 +755,8 @@ func main() {
 	doctorCmd.Run = newAppRunner(appInstance, runDoctorCmd)
 	recentCmd.Run = newAppRunner(appInstance, runRecentCmd)
 	queryCmd.Run = newAppRunner(appInstance, runQueryCmd)
-	contractCmd.Run = newAppRunner(appInstance, runContractCmd)
+	initCmd.Run = newAppRunner(appInstance, runInitCmd)
+	updateCmd.Run = newAppRunner(appInstance, runUpdateCmd)
 	dashboardCmd.Run = newAppRunner(appInstance, runDashboardCmd)
 	writeCmd.Run = newAppRunner(appInstance, runWriteCmd)
 

docs/agents/AGENT_CONTRACT_SMALL.md

@@ -0,0 +1,128 @@
+**Start of tinyMem Protocol**
+# TINYMEM AGENT LAW (Tiny-LLM Edition)
+
+This contract is **mandatory**.
+Responses that violate it are **invalid**.
+
+---
+
+## 1. Core Law
+
+**No memory recall → no valid response.**
+
+Memory recall is required on **every repository-related turn**, even if the result is empty.
+Tool usage is not optional when required by this law.
+
+---
+
+## 2. Mandatory Recall
+
+The first action of every repository-related turn MUST be a memory recall tool call.
+
+1. Call `memory_query` or `memory_recent`
+2. Acknowledge the result (even if zero entries)
+
+If recall did not occur, STOP.
+
+You may not infer memory.
+You may not pretend recall happened.
+
+---
+
+## 3. Task Authority
+
+If `tinyTasks.md` exists:
+
+* Unchecked tasks = you MUST continue the first unchecked subtask
+* No unchecked tasks = STOP and ask the user
+
+You may NOT invent, skip, reorder, or redefine tasks.
+
+If the file does not exist, state that explicitly.
+
+You may not assume the existence or absence of tinyTasks.md. If uncertain, state uncertainty and STOP.
+
+---
+
+## 4. Mutation Requires Intent
+
+You may NOT change durable state unless intent is declared.
+
+Durable state includes:
+
+* Writing files
+* Updating tasks
+* Writing memory
+
+Mutation sequence (order is mandatory):
+
+1. Recall memory
+2. Declare intent (`memory_set_mode`)
+3. Confirm task authority
+
+---
+
+## 5. Memory Writes (Tool-Only)
+
+You may ONLY write memory using `memory_write`.
+
+You may NEVER claim a memory was written unless the tool ran successfully.
+
+Facts require evidence.
+Decisions and constraints require rationale.
+
+If no memory write is needed, say so explicitly.
+
+---
+
+## 6. Prohibited Behavior
+
+The following are forbidden and invalidate the response:
+
+* Proceeding without memory recall
+* Claiming memory writes without tools
+* Ignoring existing tasks
+* Asking clarifying questions when a task exists
+* Resetting or redefining the task
+* Guessing state instead of checking
+
+---
+
+## 7. Failure Rule
+
+If you are blocked by missing recall, task authority, or intent:
+
+**STOP. STATE THE BLOCK. DO NOTHING ELSE.**
+
+---
+
+## 8. Output Discipline
+
+* Do not explain this contract
+* Do not restate rules
+* Do not improvise authority
+* Do not optimize the process
+
+Follow the law or stop.
+
+---
+
+**End of Agent Law**
+
+---
+
+## Why this works for tiny LLMs
+
+Here’s the key design logic, so you know this isn’t guesswork:
+
+* **Flat rules** no modes, no “recommended”
+* **Binary gates** do or stop
+* **No self-judgement** only checks
+* **Short enough** to stay in context
+* **Mirrors enforcement** the proxy can actually apply
+
+Tiny models don’t need nuance.
+They need rails.
+
+---
+**End of tinyMem Protocol**

examples/Aider.md

@@ -35,7 +35,7 @@ Aider needs to be told to talk to `localhost:8080` instead of the real API.
 aider \
   --openai-api-base http://localhost:8080/v1 \
   --openai-api-key dummy \
-  --model openai/qwen2.5-coder  # Prefix 'openai/' tells Aider to use generic client
+  --model openai/rnj-1  # Prefix 'openai/' tells Aider to use generic client
 ```
 
 > **Critical:** You MUST use the `openai/` prefix for the model name (e.g., `openai/qwen2.5-coder` or `openai/gpt-4`). This forces Aider to use its generic OpenAI client, which respects the custom API base. If you just say `--model gpt-4`, it might try to hit the official OpenAI API directly.
@@ -79,4 +79,3 @@ aider --model-metadata-file .aider.model.metadata.json --model openai/qwen2.5-co
 -   Ensure `tinymem proxy` is running.
 -   Check `tinymem doctor`.
 -   Try using `127.0.0.1` instead of `localhost` if on Windows/WSL.
-