# rag-workflow

A thin MCP server plus an agent workflow that gives every coding session memory:
project context is retrieved from an [AnythingLLM](https://anythingllm.com) RAG at
task start and written back, human-approved, when a task establishes durable facts.

The server wraps the AnythingLLM Developer REST API with five workflow-shaped
tools instead of a generic chat proxy. The kit (`workflow/`) is the read/write
procedure as two agent skills, plus a session-start trigger.

## Requirements

- Node >= 24 (target the latest locally installed nvm version).
- A running AnythingLLM instance (self-hosted or desktop) with a Developer API
  key (Settings -> Developer API).

## Tools

| Tool                   | Endpoint                                      | Purpose                                                            |
| ---------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
| `rag_find`             | `GET /v1/workspaces`                          | Match a repo (`owner/repo`) to its workspace by exact display name |
| `rag_search`           | `POST /v1/workspace/{slug}/vector-search`     | Scored semantic chunks, no LLM generation                          |
| `rag_create_workspace` | `POST /v1/workspace/new`                      | Onboard a repo                                                     |
| `rag_write`            | `POST /v1/document/raw-text`                  | Embed a curated markdown doc; upserts by title                     |
| `rag_forget`           | `POST /v1/workspace/{slug}/update-embeddings` | Delete the doc under a title                                       |

Identity is the workspace **name**, never the slug: AnythingLLM strips `/` and
rewrites `.` to `-dot-` in slugs, so slugs collide. Doc titles are compared
extension-stripped because stored titles lose their extension (`.md` -> `.txt`).
Both rules are proven in `docs/resolver-spec.md` and
`docs/context-schema.md`.

## Install

```bash
pnpm install
pnpm build
```

Register with any MCP client (example for a global MCP config file):

```json
{
  "mcpServers": {
    "anythingllm-rag": {
      "command": "node",
      "args": ["/absolute/path/to/rag-workflow/dist/index.js"],
      "env": {
        "ANYTHINGLLM_BASE_URL": "http://your-anythingllm-host",
        "ANYTHINGLLM_API_KEY": "your-developer-api-key"
      }
    }
  }
}
```

Keep the API key out of version control.

## Workflow kit

`workflow/` holds the procedure that turns the five tools into session memory,
written for the [pi](https://github.com/badlogic/pi-mono) coding agent but
portable to any agent with skills plus a prompt-injection hook:

- `skills/find-context/SKILL.md` — read path: identify repo (git origin, cache
  fallback), find workspace, search per concern, adopt or propose onboarding.
- `skills/write-back/SKILL.md` — write path: draft curated docs per
  `docs/context-schema.md`, get per-doc human approval, upsert.
- `extensions/rag-trigger.ts` — injects the context-check instruction on the
  first prompt of each session in a git repo.
- `AGENTS.md` — standing instructions, fallback when no hook is available.

Install by copying the skills and extension into your agent's discovery paths
(pi: `~/.agents/skills/`, `~/.pi/agent/extensions/`).

## Verify

Against a live instance, exercising all five tools and the upsert/no-stale rule:

```bash
ANYTHINGLLM_BASE_URL=... ANYTHINGLLM_API_KEY=your-key pnpm smoke
```

## License

MIT