AssetRAG

A local-first, licence-aware code library and verified engineering memory for Claude Code (any MCP client works).

It finds tested building blocks, verified bug fixes and known-good packages before your agent reinvents them, and tells it honestly when nothing fits.

▶ Watch the 95-second film  ·  Install  ·  Tour  ·  Honest numbers  ·  Disclaimer

Silent preview. Click it to play the full 95-second film (1080p, with sound). Every terminal in it is a real recording of the real tool; the soundtrack was synthesized for this project.

$ assetrag know "tail a log file without busy-waiting"
$ assetrag search "go cli progress bar" --category cli
$ assetrag repomap .          # ranked outline of a codebase in a token budget
$ assetrag doctor             # health score for the whole setup

Linux only, for now. AssetRAG is developed and tested on Linux. macOS and Windows are not supported yet. It also needs Python 3.11+ and git.

Read DISCLAIMER.md first. No warranty, not legal advice, and you (not the author) are responsible for whatever assets or code you or your AI agent end up using. AssetRAG ships no third-party assets; it indexes what you ingest, each under its own licence.

Contents

Why · Install · A tour with real screenshots · What you get · Use with Claude Code · Commands · Safety model · Honest numbers · What is not built · Docs · Licence

Related MCP server: codememory

Why

A coding agent starts every task cold. It rewrites the retry loop you already have a tested version of, picks a package whose licence you cannot ship, re-derives a fix for an error that has a known cause, and reads half your repository to find one function. AssetRAG is the memory and the shelf it lacks:

• A shelf of licensed, human-made building blocks. Whole-repo ingestion with each project's own LICENSE fingerprinted and checked against a permissive allowlist. Importing an asset copies it into your project and writes the notices.

• Verified knowledge. Recipes and bug fixes whose repro and fix were actually executed in a sandbox, plus rules, playbooks and package guidance with verified licences.

• A small, honest context footprint. A ranked repo map and a prompt hook with a hard token cap, so it saves context instead of eating it.

• Honest empty states. When nothing relevant exists, it says no_good_match rather than guessing.

It runs entirely on your machine: no account, no telemetry, no network required for the happy path.

Install (Linux, one line)

curl -fsSL https://raw.githubusercontent.com/mttcn83/assetrag/main/scripts/install.sh | sh

Prefer to read it first? scripts/install.sh is ~100 lines. It installs with pipx/uv (no sudo, no system changes), then runs assetrag setup. Or by hand: pipx install git+https://github.com/mttcn83/assetrag && assetrag setup.

assetrag setup is idempotent. It creates the data dir, asks where semantic search should get its embeddings (default EmbeddingGemma; local Ollama, LM Studio or llama.cpp/Unsloth, or hosted OpenRouter, OpenAI, Gemini or any OpenAI-compatible endpoint, with an API key where needed), offers to download EmbeddingGemma if a local provider lacks it, lets you pick another model if a hosted provider has no EmbeddingGemma, loads the built-in verified knowledge, and prints the command to register the MCP server with Claude Code. Skip the questions with --keyword-only or --provider openrouter --embed-model ...; change your mind later with assetrag setup --reconfigure. Details: docs/INSTALL.md. Remove everything with assetrag uninstall (dry run; --yes removes config and timers, --purge also deletes the data dir).

Requirements: Linux, Python 3.11+, git. Optional: bubblewrap (sandbox for running recipe tests), clamav (malware scan), gh (licence checks, updater), an embedding provider (local or hosted; semantic search; without one it runs keyword-only and says so). The installer is exercised in containers on Arch, Debian, Ubuntu, Fedora and Alpine (scripts/container-test.sh).

A tour with real screenshots

Every image below is a frame from the launch film, which was rendered from real recordings of the CLI and MCP server (isolated demo directory, keyword-only mode, nothing typed by hand).

Your AI uses it. You can check every answer.

When you type a prompt, the optional Claude Code hook adds a short, capped note before Claude answers: a ranked hit or two, each with an id. Nothing is hidden. Run assetrag kshow <id> yourself and you get the same entry, including the repro, the fix, and how it was verified.

An MCP server your agent can call

18 tools over stdio: asset and knowledge search, licence checks, repo map, rules, secret scan, lessons and failure memory. Results are returned as untrusted data, and the server's instructions tell the client to treat them that way.

Verified bug-fix memory

Paste the exact error, get a fix whose reproduction and fix were both run in a no-network sandbox (repro exits non-zero, fix exits zero). A hit is a hypothesis to test, and a nonsense error gets an honest "no match".

Playbooks, recipes and package guidance

Pick a method for the situation (root-cause, refactor-safe, perf-optimise and more), grab a recipe with executed tests, or learn which mature library to use and under what licence. Playbooks are checklists and are labelled unbenchmarked by the product itself.

Rules and a secret scan

Engineering rules for a task in a few lines, and assetrag scan-code runs the rule detectors over a file (exit code 1 if anything is found).

Licensed assets, privacy included

Search, read the licence verdict and its evidence hash, import with notices written for you. assetrag audit flags hotlinked CDNs, fonts and trackers in a project.

Small context, on purpose

assetrag repomap outlines a codebase in a token budget, and the optional Claude Code prompt hook injects only what is relevant, capped at 520 tokens. assetrag context "<prompt>" shows exactly what the hook would inject for a prompt, with scores and drop reasons.

Safe to ingest

Ingestion clones, scans with ClamAV, then applies licence and quality gates before admitting anything. assetrag scan is the release gate and writes security-report.md.

Upkeep you can trust

doctor gives a health score, snapshot and rollback protect the database, recheck re-runs every authored test against today's toolchains, and update is opt-in, never deletes, and can run from a weekly systemd user timer you enable yourself.

What you get

Architecture: docs/ARCHITECTURE.md.

Use with Claude Code

claude mcp add assetrag -- assetrag-mcp

Retrieved text is wrapped as untrusted data, and the server tells the client to treat it that way. Optional prompt hook: integrations/settings.hook.json. The hook adds a short, capped note (a ranked hit or two, or a playbook for the situation) to prompts where it is likely to help, and stays silent on trivial edits and plain questions.

Nothing forces the agent to use AssetRAG. The server's instructions say when it is worth calling (first contact with a repo, an exact error, a common pattern, a new dependency, before finishing code that touches secrets or input) and when to skip it.

Commands at a glance

Run assetrag --help or assetrag <command> --help for the full list.

Safety model

• Licences. Only permissive licences on the allowlist are admitted. Each repo's own LICENSE is fingerprinted, and an upstream relicence puts the asset in quarantine. Evidence hashes are stored, and THIRD_PARTY_NOTICES is written on import. See docs/LICENSING.md.

• Untrusted data. Everything retrieved, including file contents, is treated as untrusted third-party text. Prompt-injection patterns are flagged.

• Sandbox. Recipe and bug-fix tests run under bubblewrap with no network. Without it, entries load but are labelled unverified here.

• Malware. ClamAV gate on ingestion and a release scan (optional dependency).

• No elevation. Install is user-level. Nothing silently needs sudo, and the updater is opt-in and never deletes.

• Privacy. Local-first, no telemetry. The audit warns when a project pulls fonts, scripts or trackers from third-party hosts.

More in docs/SECURITY.md.

Honest numbers

Measured on the author's machine and library (the library holds 16,064 assets and 4,247 knowledge entries there; you build your own by ingesting). Keyword-only mode.

The retrieval set is kept in the author's development tree (not shipped) and was used while tuning, so treat hit@3 as optimistic. Whether AssetRAG makes Claude measurably faster in real tasks has not been measured yet: the bench claude-ab command exists but has never been run, because it spends API budget.

What is not built

Starter projects, automatic lesson capture, adapted snippets and successor detection are not in the product and are not advertised. Semantic (embedding) search is implemented and unit-tested but was not exercised in the film or the numbers above, which are keyword-only.

Docs

Install notes · Architecture · Licensing policy · Security · Troubleshooting · Disclaimer

Licence

Apache-2.0, see LICENSE and NOTICE. Dependencies: THIRD_PARTY_NOTICES.md. Licensing policy: docs/LICENSING.md. Security: docs/SECURITY.md. The launch film's visuals are rendered from the real tool; its soundtrack was synthesized for this project (no third-party music).