Agent Clip: Agentic Loop with Memory, Tool Use, and Vision Inside Pinix

What Agent Clip Is and What Pinix Is

Pinix is a platform for running modular service units called Clips. Each Clip is a packaged service with a defined command interface that Pinix can install, upgrade, and invoke. Agent Clip is one such Clip: it provides an AI agent that accepts conversational messages, runs an agentic loop against an LLM, and returns responses.

The agent is not a thin wrapper around a chat API. It maintains persistent memory across conversations, can invoke other Clips as tools, can browse the web and capture screenshots for vision input, and stores files in a local data/ directory that persists between sessions.

The package format (.clip) is a ZIP archive. Installing it adds the agent as a registered service in Pinix. Upgrading with a new .clip file preserves the data/ directory, so memory and configuration survive updates. This makes Agent Clip a deployable, stateful AI assistant for a Pinix environment rather than a one-off script.

The Three Memory Layers

The README documents three distinct memory mechanisms that operate together.

Facts are persistent notes the agent stores explicitly. The agent calls memory store to save a fact, memory facts to list all stored facts, and memory forget to delete one. Facts survive session restarts and upgrades because they live in the data/ directory.

Summaries are LLM-generated per-run summaries. After each agentic loop cycle (a Run), the agent produces a summary of that run and stores it with an embedding.

Semantic search operates over the run summaries using cosine similarity on the stored embeddings. When a new message arrives, the agent can call memory search to retrieve summaries of past runs relevant to the current context. This gives the agent access to older conversation context beyond its active context window, without storing the full message history indefinitely.

The combination means the agent can recall a specific fact you explicitly told it, remember what happened in a recent session, and surface older relevant conversations through vector similarity.

Building and Deploying the Clip

The Makefile targets cover the full development and deployment workflow. Local development on macOS uses:

make dev

This builds a macOS binary and initializes the data/ directory from the seed/ templates. For first-time frontend setup:

cd ui && pnpm install && cd ..

To package and deploy for the production BoxLite VM (linux/arm64):

make deploy

This cross-compiles the Go binary for linux/arm64 and builds the frontend. To produce a distributable .clip package:

make package

The output is dist/agent.clip. Install it to Pinix with:

pinix clip install dist/agent.clip

Upgrading later without losing the data/ directory:

pinix clip upgrade dist/agent.clip

Sending a message from the command line uses the agent-local binary:

bin/agent-local send -p "hello"

Cross-Clip Tool Use and File I/O

The agent's internal tool set maps to standard Linux-named commands operating on the data/ directory: ls, cat, write, stat, rm, cp, mv, and mkdir. These are the agent's file system tools. They are invoked by the LLM during a Run when it decides to read or write a file.

Beyond the local file system, the agent can invoke other registered Clips as tools:

clip <name> <command> [args]

The clip pull and clip push commands transfer files between the local data/ directory and another Clip's data directory. The README refers to Edge Clips as an example, noting that iPhone capabilities can be accessed this way. The configuration in data/config.yaml lists the available Clips with their URLs and authentication tokens:

clips:
  - name: sandbox
    url: http://localhost:9875
    token: <clip-token>
    commands: [bash, read, read-b64, write, write-b64, edit]

This architecture means Agent Clip is not self-contained: its tool capabilities are bounded by which other Clips are registered and available.

Vision, Browser Integration, and the Web UI

Browser screenshots are automatically saved to data/images/ when the agent takes them, and the image is attached as vision content to the next LLM API call. The LLM can then reason about what it sees in the screenshot. The agent returns a pinix-data:// URL for rendered display in the Clip Dock on Desktop or iOS.

The browser tool is accessed by the agent internally as browser <action> [params]. The browser endpoint is configured in data/config.yaml. This is a remote browser, not a local one: the agent sends browser control commands over the configured endpoint.

The web UI is built with React, Vite, and Tailwind CSS v4. It uses Streamdown for Markdown rendering, with plugins for Shiki syntax highlighting, CJK typography, LaTeX equations via KaTeX, and Mermaid diagrams. The UI is compiled with make ui into the web/ directory, which Pinix serves through the Clip Dock.

Configuration and Multi-Provider LLM Support

All configuration lives in data/config.yaml and is managed through the config command, which the agent also uses internally. The structure supports multiple LLM providers:

name: pi
providers:
  openrouter:
    base_url: https://openrouter.ai/api/v1
    api_key: <key>

llm_provider: openrouter
llm_model: anthropic/claude-3.5-haiku
embedding_provider: openrouter
embedding_model: openai/text-embedding-3-small

The config command handles updates without editing the file directly. The system prompt is configurable in the same file. Changing the active model or provider requires updating llm_provider, llm_model, and the credentials under providers.

Text Processing Tools and Async Execution

Beyond file I/O, the agent has access to text processing commands: grep, head, tail, and wc. These follow the standard Linux command interface and operate on files in the data/ directory. Combined with the file I/O tools, the agent can read a file, search for patterns, and write processed results back without leaving the agentic loop.

The send command accepts an --async flag:

bin/agent-local send -p "hello" --async

With --async, the command returns a run ID immediately rather than waiting for the response. The get-run command retrieves the status and output of an async run by its ID, and cancel-run cancels one that is still in progress. This is relevant for long-running tasks where the caller does not want to block while the agent executes multiple tool steps.

A topic is a named conversation namespace. All messages belong to a topic. Topics are created automatically on the first send or explicitly via create-topic. List all topics with list-topics, which sorts them by last message time. Each agentic loop cycle is a Run: one user message in, multiple LLM calls and tool executions, and a final stop. Runs within a topic form the conversation history.

Agent Clip Compared to a Standard LangChain Agent

LangChain and LangGraph provide general-purpose Python frameworks for building agentic systems. They are platform-agnostic: you can deploy a LangChain agent to any Python runtime, any cloud function, or any server that runs Python. The tool ecosystem covers databases, APIs, web search, and custom functions.

Agent Clip is platform-specific. It runs only on Pinix and its BoxLite VM. The tool set is defined by which other Clips are registered in your Pinix environment. There is no plugin ecosystem analogous to LangChain's integrations library.

The trade-off is that Agent Clip is pre-integrated with the Pinix deployment and upgrade lifecycle, the Clip Dock UI, the vision pipeline, and the three-layer memory system. A LangChain agent requires assembling these components from separate libraries and hosting infrastructure. For a developer already inside the Pinix ecosystem, Agent Clip provides a complete agentic system with less assembly. For a developer who needs Python tooling, cloud deployment, or LangChain's integrations, the platform dependency is a hard constraint.

Editorial conclusion

Agent Clip is the right starting point for a developer building an agentic assistant specifically for the Pinix ecosystem. The memory architecture, cross-Clip tool invocation, and vision integration are ready to use; the configuration is a single YAML file. The limitation is platform lock-in: nothing here runs outside Pinix. Before adopting it, confirm you have a working Pinix installation and understand the BoxLite VM constraints for the target deployment. The last push was on 2026-05-17.

Frequently asked questions

Official sources

1. epiral/agent-clip on GitHub
2. Issues
3. README