LocalRecall overview¶
LocalRecall is a RAG collection store. It ingests files, splits them into chunks, asks an external embeddings endpoint for a vector per chunk, writes those vectors into a pluggable backend, and answers similarity queries against them.
It runs no models. There is no ONNX, GGML or tokeniser dependency anywhere in
its go.mod; every embedding is an HTTP POST to an OpenAI-compatible
/embeddings endpoint (normally LocalAI). If that endpoint is down, LocalRecall
can still list and serve files, but it cannot index or search. See
embeddings.
At v0.6.4 the whole project is roughly 9,600 lines across 65 files. It is small enough to read end to end, and this chapter is written from a full read of the Go sources rather than from the README.
The dual nature¶
LocalRecall is simultaneously two things, and which one you are using changes where its state lives, what crosses the network, and which bugs can reach you.
| Standalone HTTP service | Importable Go library | |
|---|---|---|
| Entry point | main.go → startAPI (main.go:95-97) |
rag.NewPersistent*Collection (rag/collection.go:20,40,63) |
| Configuration | 16 environment variables, read in main.go |
constructor parameters only — rag/ reads no environment at all |
| Transport to caller | HTTP /api/collections/... on :8080 |
in-process Go method calls |
| Web UI | yes, embedded static/ FS |
no |
| Consumers | anything that speaks HTTP; LocalAGI when LOCALAGI_LOCALRAG_URL is set |
LocalAGI by default, and therefore LocalAI |
The main package holds exactly four files: main.go (97 lines), routes.go
(577), static.go (32), and internal/versioning/version.go (3, a separate
package). That is ~674 lines of Echo shell over the library — everything
substantive lives under rag/ and pkg/.
The layering is not incidental. Nothing under rag/, rag/engine/ or
pkg/chunk/ imports Echo or net/http for its own serving; the dependency arrow
points only main → rag. Every value a collection needs, including the
embeddings client itself, arrives as a constructor argument. That is precisely
what makes in-process embedding possible: a host application supplies its own
*openai.Client and gets a *PersistentKB back, with no HTTP server, no port,
and no environment parsing in between.
Who consumes it which way¶
flowchart TD
subgraph LAI["local-ai process"]
AG["LocalAGI collections layer<br/>(library)"]
LR1["LocalRecall rag pkg<br/>(library)"]
EMB["embeddings endpoint"]
end
subgraph LRS["localrecall process (optional)"]
API["Echo API :8080"]
LR2["LocalRecall rag pkg"]
end
PG[("PostgreSQL")]
AG -.->|in-process| LR1
LR1 -->|"HTTP POST /embeddings"| EMB
LR1 -->|"pgx (optional engine)"| PG
AG -->|"HTTP /api/collections<br/>(only if LOCALAGI_LOCALRAG_URL set)"| API
API -.->|in-process| LR2
LR2 -->|"pgx (optional engine)"| PG
- LocalAGI embeds the library by default.
LocalAGI/webui/collections/inprocess.gocallsrag.NewPersistentChromeCollection/...LocalAICollection/...PostgresCollectiondirectly and stores the results in amap[string]*rag.PersistentKB. SettingLOCALAGI_LOCALRAG_URLswitches it to an HTTP backend built on LocalAGI's ownpkg/localragclient — not LocalRecall'spkg/client, which no LocalAGI file imports. - LocalAI never touches LocalRecall's API directly. A search of LocalAI's Go
sources for
mudler/localrecallreturns zero hits; the module appears in itsgo.modas// indirect. Knowledge reaches LocalAI through LocalAGI's collections layer. The dependency chain is LocalAI → LocalAGI → LocalRecall, and it is a compile-time chain. - Third-party callers have two supported options:
pkg/client(HTTP, against a running server) or theragpackage (in-process). Both are exported and documented in architecture.
Three LocalRecall versions are in play at once¶
This trips people up when comparing "knowledge in LocalAI" with "knowledge in standalone LocalRecall".
| Deployment | LocalRecall version linked |
|---|---|
| Standalone LocalRecall today | v0.6.4 |
| LocalAI v4.8.2 | v0.6.3 (plain tag, LocalAI/go.mod:241) |
A go build of standalone LocalAGI v2.9.0 |
v0.6.3-0.20260618142827-d0073dd5dc32 |
LocalAGI pins a pseudo-version — a commit dated 2026-06-18, after the v0.6.2
tag and before the v0.6.3 tag (2026-06-26). LocalAI requires the plain tag
v0.6.3. Under semver a pre-release suffix sorts below the plain version, so
Go's minimal version selection resolves the combined build to the real v0.6.3
release. LocalAI therefore links a newer LocalRecall than standalone LocalAGI
does.
The practical consequence: features that landed in v0.6.4 — notably
BM25_TEXT_CONFIG and the pg_textsearch v1.3.1 pin — are present in neither
linked version. Parity between the two deployments is coincidental, not
contractual. Version-sensitive claims in this chapter are stamped v0.6.4 unless
stated otherwise.
What LocalRecall is not¶
- Not a memory system. The README describes managing "long-term and
short-term memory" (
README.md:16). In the code there is no memory endpoint, no recency decay, no salience, no summarisation, no eviction and no TTL. Acreated_atvalue is written into chunk metadata and never read by anything. Agent memory is built on top of LocalRecall's collection primitives by LocalAGI — see terminology. - Not a document converter. Only
.pdf,.txtand.mdare indexable on the upload path. Everything else is stored, listed, downloadable and permanently unsearchable. This is the single most common surprise in the whole component; ingestion covers it. - Not a reranking pipeline. A grep for
rerankacross the sources returns zero hits. There is no query rewriting, no HyDE, no multi-query and no cross-encoder. Retrieval is one call into the backend.
Nine places the README and the code disagree¶
Each is confirmed against v0.6.4 source. Believe the source column.
| # | README says | Code does | Covered in |
|---|---|---|---|
| 1 | Supports raw text inputs (README.md:22) |
No such route (routes.go:177-188), no such UI control (static/js/collectionManager.js:329-341) |
ingestion |
| 2 | Fully local, no external cloud dependencies (README.md:58) |
Web UI loads four public CDNs (static/index.html:7-10) |
installation |
| 3 | .env file support (README.md:216) |
No dotenv dependency; env_file commented out (docker-compose.yml:40) |
installation |
| 4 | Two engines: Chromem, PostgreSQL (README.md:18-21) |
Three; localai is selectable (routes.go:99) |
storage |
| 5 | COLLECTION_DB_PATH is "for Chromem engine" (README.md:196) |
Used by every engine for collection-*.json (rag/collection.go:27,45,70) |
storage |
| 6 | Env table omits three variables (README.md:194-212) |
BM25_TEXT_CONFIG, LOCALRECALL_REPOPULATE_DELETE, LOCALRECALL_PDF_EXTRACT_TIMEOUT all exist |
installation |
| 7 | Go 1.16 or higher (README.md:71) |
go 1.25.0 (go.mod:3), builder image golang:1.26 (Dockerfile:5) |
installation |
| 8 | Entry content returns chunks[] + count (README.md:259) |
Returns content (one string) + chunk_count (routes.go:370-375) |
collections |
| 9 | Pull latest-postgresql (README.md:156) |
latest=false on that image (.github/workflows/image.yml:98) |
installation |
OPENAI_BASE_URL is a tenth case of a different kind: the README lists it as an
ordinary optional row, but the code makes it effectively mandatory. That one is
in embeddings because the failure mode needs explaining.
Where to go next¶
| Question | Page |
|---|---|
| How do the library and service halves fit together? | architecture |
| How do I run it? | installation |
| What is the HTTP API? | collections |
| Why is my uploaded file not searchable? | ingestion |
| Why are my chunks so small? | chunking |
| Where do embeddings come from? | embeddings |
| What does the similarity number mean? | retrieval |
| chromem or PostgreSQL? | storage |
| End-to-end pipelines | rag |
| It is broken | troubleshooting |
Upstream references¶
main.go— service entry point, environment parsing, embeddings client construction. Source-verified against v0.6.4, validated 2026-08-17.routes.go— the complete route registration at lines 177-188. Validated 2026-08-17.rag/collection.go— the three exported collection constructors andListAllCollections. Validated 2026-08-17.rag/persistency.go—PersistentKB, on-disk layout, chunkable-file gate. Validated 2026-08-17.go.mod— no model runtime dependency;sashabaranov/go-openai v1.37.0at line 16. Validated 2026-08-17.README.md— the documented claims in the discrepancy table. Validated 2026-08-17.- LocalRecall release v0.6.4 — validated 2026-08-17.
- LocalAI
go.mod— line 241,localrecall v0.6.3 // indirect. Validated against v4.8.2, 2026-08-17. - LocalAGI
go.mod— line 21, thev0.6.3-0.20260618142827-d0073dd5dc32pseudo-version. Validated against v2.9.0, 2026-08-17. - LocalAGI
webui/collections/inprocess.go— the in-process backend and its engine switch. Validated against v2.9.0, 2026-08-17.