HamsterBase: a local-first web archive that is not actually open source

The repository is not the product, and the README says so

HamsterBase is described as a self-hosted, local-first web archive application, and the first thing the README does is deny the obvious interpretation. Asked whether HamsterBase is open source, the answer in the README is that it is not open source software, and is only distributed through GitHub.

That is an unusual thing to state plainly, and it changes what an engineer is looking at. The repository root holds a package.json, a Readme, a home image, a License file, a .prettierrc and an sdk directory. There is no application source tree. The code that is public is the SDK and a set of browser extensions, and the application binary is distributed separately through the project's own channels.

The distinction is easy to miss in a search result, because the repository looks like a normal source repository with a README, a licence file and a package manifest. It is not one. Anyone planning to build on HamsterBase, self-host it, or redistribute it has to start with the end user licence agreement linked from the project page rather than with the code, and that document is the actual contract.

The other thing worth noting early is the naming. The project is also known as a knowledge collector rather than strictly an archive, since the features around annotation and views make it closer to a reading notebook that happens to keep the original pages.

What it stores: HTML, MHTML and Webarchive side by side

The feature list in the README covers storage formats, annotation, filtering, search and two conveniences that are easy to underestimate.

On formats, HamsterBase stores, manages and previews HTML, MHTML and Webarchive documents. Three formats for the same kind of artifact is a deliberate choice rather than a quirk. MHTML keeps the page in a single file, and Webarchive is a container format, so an archive entry can be self-contained and moved between machines without losing its assets.

On annotation, the README states that webpages can be highlighted and annotated, and that annotation can be added retroactively. The retroactivity matters more than it first appears. A highlights-only tool forces a decision at capture time about what is worth keeping, while retroactive annotation lets you treat the archive as a corpus you can return to and mine later.

The remaining features are the ones that turn a pile of saved files into something usable. Custom views filter the stored webpages, so you can organise without moving anything between folders. The README also lists a way to turn views into RSS feeds, which is a neat trick for a local collection: a view you subscribe to in any feed reader. Full text search runs across the archive, and dark mode is listed for the same reason the other quality-of-life items are: this is software people sit in front of for hours.

Notably absent from the list is any sign of a server component. The README states there is no dependency on any server and that all data is local first, which is the architectural commitment that everything else follows from.

No server dependency is the whole point, and the cost is shared state

The claim that nothing depends on a server is the difference between HamsterBase and hosted read-later services, and it is worth being precise about what it buys and what it costs.

What it buys is durability of the archive. Pages you capture live on your disk, in a format you can read with other tools, and the application is not a thin client waiting on someone else's database to hand you back a copy of a page that may have changed since you saved it. For a knowledge collector whose whole purpose is to hold a snapshot you will come back to in a year, that is the point.

What it costs is that there is no account, no sync, and no shared database. If you want the same archive on a laptop and a desktop, or on a phone, you are moving files yourself, and the project answers that need with extensions rather than with a backend. The README lists extension-based sync for Logseq, Obsidian and SiYuan, all three described as syncing your highlights and notes into those tools.

That is an interesting architectural choice. Rather than building a multi-device sync service, the project pushes the highlights and notes out to note-taking applications that already have one. The trade is that the archive itself, as opposed to the notes taken from it, does not follow you to another machine automatically.

For an individual on one laptop, none of this is a problem. For a team, it is a real constraint, and it is the constraint that would push you toward a different tool.

The SDK is the open source part, and the extensions ride on it

The public code is an SDK published to npm under the name @hamsterbase/sdk, linked from the README as open source and also listed as one of the features. The repository layout confirms the shape: an sdk directory at the root, with the root package.json acting as a thin wrapper around it.

The root scripts delegate everything into that directory, so the wrapper does nothing more than change directory and call the inner npm script:

  "scripts": {
    "build": "cd sdk && npm run build",
    "pub": "cd sdk && npm publish",
    "postinstall": "cd sdk && yarn"
  },

There is a mismatch worth flagging: the postinstall hook runs yarn inside the sdk directory, while the build and publish paths use npm. A developer with npm only may find the postinstall step failing, since the repository does not say which package manager is expected inside sdk. The root manifest also carries an empty devDependencies object and a version of 0.0.0, which tells you the root package is a task runner rather than a published artifact. The real version number for the SDK lives in the sdk package itself.

The extensions are the other open source piece. The README lists four: the official web highlighter extension hamsterbase-highlighter, and three sync extensions for Logseq, Obsidian and SiYuan, each described as syncing your highlights and notes into the corresponding application. Four separate repositories rather than a monorepo, which keeps each extension small and lets a user install only the one that matches their notes.

Install instructions live on the website, not in the repository

There is no install command in this repository, and the README says so directly. Installation is delegated to a guide hosted on the project site, and the README links the download and setup instructions from there.

This is consistent with the rest of the project. The application is distributed through the project's own channels rather than through a package registry, the download is versioned separately from the git tags, and the setup steps involve an installer rather than a package manager entry. If you are evaluating the project, the install guide is the first place to look, and the fact that the repository contains no build recipe for the application itself is a signal that a self-hosted build from source is not the intended path.

The extensions are the opposite case. Those are source repositories you clone and build, and the root scripts shown earlier are the entry point for working on the SDK. So the practical split is: application from the website, SDK and extensions from the repository.

One detail to watch is in the release history. The most recent tag is named 2026, with the description stating that HamsterBase releases have moved to the official website, in both English and Chinese. The previous tags are plain version numbers, 0.15.0 from February 2025 and 0.14.0 from November 2024. Once releases stop appearing as GitHub tags, tracking what version you are running means checking the application itself rather than the repository, and the git history stops being a reliable way to see what changed.

The licence file is the deciding document, and the alternatives are elsewhere

The repository carries a file named License at the root rather than the usual LICENSE, and it is not one of the licences GitHub can classify automatically, which is why the project metadata shows the licence as other. The README links an end user licence agreement, a privacy policy and a credits page from the project site. For an application you install and run locally, an end user licence agreement is a normal thing to accept. For software you intend to read, change and redistribute, it is the point where this project stops being a candidate.

That is the boundary to state plainly. If your requirement is a self-hosted archive you can audit, patch or ship inside a product, this project does not meet it, whatever the repository looks like. The open SDK and the open extensions might still be useful to you, since they are separate code with their own terms, and a team could in principle build a different archive tool on top of the SDK.

The other alternative worth naming is a different workflow entirely: keep highlights and notes in an application that already syncs across your devices, using the Logseq, Obsidian or SiYuan extensions, and let the raw page captures live in whatever archive tool you already trust. You lose the custom views and the RSS conversion, and you gain a setup that needs no archive application at all.

The design decision that makes HamsterBase different from a plain note application is the local-first storage of the original documents with full text search across them. If you do not need the original pages, that is the part you are paying for and not using.

Maintenance signals: a quiet few months and a version-number scheme that changed

The last push to the repository was on 2026-05-29, and the repository is not archived. The most recent release tag shares that date, since the tag announcing the move of releases to the official website was published the same day as the final commit. Before that, the two visible version tags are 0.15.0 from 2025-02-08 and 0.14.0 from 2024-11-23.

The pattern is a project at 0.x, released roughly every few months, that has now stopped tagging releases in git. Nothing in the repository indicates a roadmap or a deprecation policy, so an adopter cannot learn from the README when a version will be dropped or how long 0.15 will be supported.

The privacy angle deserves a mention because the project advertises it explicitly. The README calls HamsterBase local-first and privacy first, and since there is no server component, there is no account and no upload of your reading history. That is a property of the architecture rather than a promise, which is the strongest kind of privacy claim available. A local archive also keeps pages you would rather not have indexed elsewhere, such as work documents you saved for reference, on hardware you control.

What this means for a decision is narrow. Individual users get a capable archive with no lock-in and no running costs. Organisations evaluating it should first read the EULA, then look at the credits and privacy pages, and then decide whether the local-first model is what they wanted or whether they needed a shared service with a server in the first place.

Editorial conclusion

HamsterBase suits an individual who wants a private, local archive of the pages they read and is prepared to accept a custom end user licence agreement and a moving release process. It does not suit a team that needs to audit, modify or redistribute the application source, because the repository states the app is not open source. Before adopting it, read the EULA linked from the project page, confirm that the SDK and the editor extensions cover the part of the workflow you need, and check the install guide, since the download and setup steps are not in the repository.

Frequently asked questions

Official sources

1. hamsterbase/hamsterbase on GitHub
2. Issues
3. Project website
4. README
5. Releases