io.github.aimnis/search
Collaborative, cache-first web search for agents — cited answers from a shared live-web pool.
Open source Repository Open in the app JSON README (API)
About
Collaborative, cache-first web search for agents — cited answers from a shared live-web pool.
Details
- Kind
- MCP servers
- Topic
- Web search, scraping & browser
- Publisher
- aimnis
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.0
- Last push
- 2026-08-07T17:31:45Z
- Repository state
- ativo
- Language
- Python
- License
- AGPL-3.0
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-08-29 03:02:24
- Origin id
io.github.aimnis/search
README
# Aimnis
### Collaborative Search for Agents
**Search once. Answer everyone.** An open-source, cache-first web-search gateway for
coding agents: ask a question and get a distilled, source-cited answer instantly from
a shared, always-current knowledge pool — so every search makes the pool smarter and
cheaper for everyone. Like RAG, but over a communal live-web pool, not your stale
private docs.
> **Status: public preview.** The hosted service is live — get a free eval key at
> **[aimnis.com](https://aimnis.com)** and point your agent at it in one minute
> ([per-agent setup](https://aimnis.com/setup)). We're proving one thing in public —
> that the cache hit rate compounds as the pool grows (the [flywheel](#the-flywheel),
> [live dashboard](https://aimnis.com/flywheel)). Follow along.
## Why
Every model has a training cutoff. The moment it ships, the world moves on — new
library versions, new APIs, new errors — and the model can't keep up without
searching the live web on every question. That's slow, expensive, and per-vendor.
Aimnis is the shared, always-current layer in front of that: the **first** thing an
agent checks. Ask a question; if it (or a semantically similar one) has been asked
before, you get a distilled, source-cited answer instantly for near-zero cost. If
it hasn't, Aimnis fetches it live, distills it, and adds it to the pool — so the
next agent to ask gets it free. The corpus captures what happened *after* every
model's cutoff, which no static training set can.
## How it works
```
query
└─ scrub secrets/PII (redacted before embed, search, distill, or storage)
└─ local embed + normalize
└─ semantic cache lookup (exact hash → vector nearest-neighbour)
├─ HIT → return the pooled, cited answer instantly (no upstream cost)
└─ MISS → live search → distill into a cited answer → quality-gate → pool it
```
- **Cache-first.** The knowledge pool *is* the semantic cache (pgvector). A
reworded question hits the same entry, so the pool compounds faster than exact
matching would.
- **Grounded, cited answers.** Misses are distilled from live web results into a
short answer with `[n]` citations back to sources — not raw links. The answer is
**AI-generated** (a model distills the sources) and labeled as such in the tool
output, so the agent always knows it's reading a machine-written summary.
- **Provenance & freshness by default.** Every answer carries its model, sources,
and a **cache timestamp** (when the answer was produced or last re-distilled —
not when it was last served), plus a relative age, so the agent (and our own
ranking) can weigh staleness and decide when to escalate to live search.
- **Cited links can be routed for a relevance signal (opt-in, aggregate-only).**
When enabled, a cited source link points at a signed `/r/…` redirect that logs
which pooled answer earned a follow-through, then forwards to the source — this
is how click-through improves ranking. The source's real host is shown inline so
the agent still sees where it's going, and the log records only *entry + source +
host + time* — **never IP, user-agent, or any user/session id**. It's telemetry on
the pool, not on you. It's off unless a signing secret is configured, tokens are
HMAC-signed (so `/r` can't be abused as an open redirector), and self-hosting
points the redirect at *your own* gateway — so clicks stay on your box.
- **Privacy-conscious ingress.** Common secret formats (API keys, tokens, private
keys, connection strings) and emails are redacted *before* a query is embedded,
sent to a search/LLM provider, or pooled; secret-dense queries are served
live-only and never stored. This is high-precision format-based scrubbing plus an
entropy pass — it catches known shapes, not every possible secret or PII, so treat
it as defense-in-depth, not a guarantee. The pipeline is open source precisely so
you can audit and extend it. **Where it runs:** self-hosted, scrubbing happens
locally, so raw text never leaves your machine. Against the *hosted* gateway, the
query is sent over TLS and scrubbed on ingress (in memory, before any provider call
or persistence) — if you need redaction to happen before the query leaves your
machine, self-host or run the local MCP server in local mode.
- **Quality-gated pool.** A distilled answer must pass a quality gate before it can
enter the pool — a bad answer degrades to raw snippets rather than poisoning the
commons.
## The flywheel
The one metric that decides whether this works: **cache hit rate vs. corpus size.**
If it climbs as the pool grows, the thesis holds. It's public from day one — trust,
made measurable.
```bash
# run the live dashboard locally (see Quickstart)
aimnis-dashboard # → http://127.0.0.1:8080 (hit-rate curve, corpus size, storage)
```
## Use it with your coding agent
Aimnis speaks [MCP](https://modelcontextprotocol.io), so any MCP-capable agent can
use it as its web-search tool. The hosted endpoint means **nothing to install**:
1. Get a free eval key at **[aimnis.com/register](https://aimnis.com/register)**
(delivered by email; metered, revocable, [terms](https://aimnis.com/terms)).
2. Add the remote MCP server to your agent:
```
URL: https://aimnis.com/mcp (MCP, streamable HTTP)
Header: Authorization: Bearer aim_YOUR_KEY
```
**Claude Code**
```bash
claude mcp add --transport http aimnis https://aimnis.com/mcp \
--header "Authorization: Bearer aim_YOUR_KEY"
```
Then, to make the model prefer Aimnis over the built-in tool, deny `WebSearch` in
`.claude/settings.json`:
```json
{ "permissions": { "deny": ["WebSearch"] } }
```
**OpenCode, OpenClaw, Hermes, Pi, REST** — copy-paste snippets at
[aimnis.com/setup](https://aimnis.com/setup) and in [`docs/mcp.md`](docs/mcp.md),
plus the `search` / `stats` tool reference. Bring your own OpenRouter/search keys
at registration and your cache misses run on your quota — with much higher limits.
Self-hosting instead? The same MCP server runs locally over stdio against your own
pool — see [Quickstart](#quickstart-dev) and [`docs/mcp.md`](docs/mcp.md).
## Quickstart (dev)
```bash
cd server
docker compose up -d # Postgres+pgvector (:5432)
# want the keyless search path too? add SearXNG (:8888):
# docker compose --profile keyless up -d
uv venv .venv && . .venv/bin/activate
uv pip install -e ".[dev]" # editable install (required — see docs)
python -m aimnis.migrate # apply migrations/*.sql
cp .env.example .env # then fill in keys if you have them
pytest # full suite against the compose DB
```
No OpenRouter key? Fine — Aimnis runs keyless (via SearXNG) and returns raw cited
snippets, spending zero upstream quota. Add `AIMNIS_OPENROUTER_API_KEY` to turn on
distillation. Live search is an ordered fallback chain — Brave → Tavily → Exa →
SearXNG — so setting any of `AIMNIS_BRAVE_API_KEY` / `AIMNIS_TAVILY_API_KEY` /
`AIMNIS_EXA_API_KEY` gives more reliable results, and a free tier that runs dry
rolls onto the next automatically. See [`server/README.md`](server/README.md) for
the component map.
## Licensing
The code is open. The corpus is a curated compilation, licensed as such.
| Part | License |
| --- | --- |
| Server core (`server/`) | **AGPLv3** — network copyleft; run a modified service, share your changes |
| SDKs & MCP client (`clients/`) | **Apache-2.0** — embed anywhere, including commercial products |
| Public knowledge-pool pages | **CC-BY-NC 4.0** applies to our *compilation* (curation, structure, presentation) |
**On the pool's contents, honestly:** pooled answers are distilled by third-party
models from third-party web results. We don't claim ownership of the underlying
facts or of upstream model outputs — CC-BY-NC covers our compilation, and any reuse
also remains subject to the terms of the original sources and the model providers.
Some provider outputs are excluded from redistribution and from any future
training-data feed wherever provider terms require it, and provider-mandated
attributions are carried through. A training-data feed is out of scope until the
flywheel is proven (see roadmap) — this repo makes no offer to license training data.
Anti-abuse thresholds (scrubbing/dedup/quality tuning) ship with safe example
defaults; production values are injected at deploy and are not part of this tree —
so publishing the ruleset doesn't hand it to poisoners.
## Status & roadmap
Gated roadmap, Gate 0 → Gate 4. **Gate 0 complete** (ToS audit, niche, naming,
licensing locked). **Gate 1 in progress** — gateway + semantic cache + public
flywheel dashboard are built and dogfooded; the pass/kill test is the hit-rate
curve bending upward. Ads, billing, community compute, and the training-data feed
are explicitly out of scope until the flywheel is proven.