src/auth.md

Agent Cache — Agentic Onboarding Instructions (/auth.md)

Welcome, AI Agent! You have routed to the Agent Cache (formerly Agent Memory) memory server.

This document serves as your guide on how to interact with this server. You MUST use this document as your primary onboarding resource, follow these instructions strictly, and interact with the server using the designated endpoints.

---

1. Authentication

Protected endpoints check for authentication using the Authorization header.

• Header format: Authorization: Bearer <AGENTCACHE_SECRET>
• If no secret is configured on the server, authentication is bypassed.
• The onboarding endpoint /auth.md and the health endpoint /agentcache/livez do not require authentication.

---

2. Core REST API Endpoints

All endpoints support application/json payloads.

Observations (Folder-scoped Memory)

The primary unit of storage is scoped to (folder_path, agent_id) pairs.

• Log Observation: POST /agentcache/observe (or POST /agentmemory/observe)
  • Payload:

    {
      "folderPath": "absolute/path/to/project",
      "agentId": "your-agent-id",
      "text": "The detailed observation text to log"
    }
    

• List Folders: GET /agentcache/folders (or GET /agentmemory/folders)
  • Returns a list of all active (folder_path, agent_id) pairs.
• Get Observations: GET /agentcache/folder/observations (or GET /agentmemory/folder/observations)
  • Parameters: folderPath (string), agentId (string).
  • Returns a list of all logged observations for that folder and agent.

Global Long-term Memories

• Save Global Memory: POST /agentcache/remember (or POST /agentmemory/remember)
  • Payload:

    {
      "content": "The fact, pattern, or workflow to remember globally."
    }
    

Search & Retrieval

• Hybrid Search: POST /agentcache/search (or POST /agentmemory/search)
  • Performs keyword (BM25) + vector (semantic) hybrid search.
  • Payload:

    {
      "query": "search term",
      "limit": 10,
      "folderPath": "optional filter path",
      "agentId": "optional filter agent"
    }
    

Activity Feed

• Timeline: GET /agentcache/timeline (or GET /agentmemory/timeline)
  • Returns all observations and memories sorted chronologically.
  • Parameters: folderPath (optional), agentId (optional), limit (optional).

Forget & Clean up

• Forget Item: POST /agentcache/forget (or POST /agentmemory/forget)
  • Payload (Memory): {"memoryId": "uuid-here"}
  • Payload (Folder Pair): {"folderPath": "absolute/path", "agentId": "agent-id"}

---

3. Model Context Protocol (MCP)

Agent Cache exposes Model Context Protocol (MCP) tools for agents equipped with MCP clients.

• Get Tools Schema: GET /agentcache/mcp/tools (or GET /agentmemory/mcp/tools)
• Call Tool: POST /agentcache/mcp/tools (or POST /agentmemory/mcp/tools)
  • Payload:

    {
      "name": "tool_name",
      "arguments": { ... }
    }
    

Available MCP Tools

Tool Name	Description	Required Arguments
agent_observe	Log observation to a folder/agent pair	folderPath, agentId, text
agent_remember	Save a global long-term memory	content
cache_recall	Query folder observations and global memories	query
cache_smart_search	Hybrid semantic + keyword search	query
cache_save	Save an important insight/decision to global memory	content
cache_forget	Delete a global memory or all observations for a pair	(one of memoryId, folderPath + agentId)
cache_folders	List all folder-agent memory scopes	None
cache_folder_observations	Get observations for a specific folder/agent pair	folderPath, agentId
cache_timeline	Retrieve activity feed of observations	None
memory_export	Export cache data as JSON	None
memory_diagnose	Run health checks and count database items	None

---

4. Web UI Dashboard

The visual viewer dashboard is accessible at /viewer. It provides tabs to inspect:

1. Folders: View folder observations list and logs.
2. Memories: Browse and search global memories.
3. Graph: Force-directed relation visualizer.
4. Timeline: Scrollable real-time chronological activity feed.