AutoGineer
Generated banner for zer0dex
Generated logo for zer0dex

zer0dex

Memory frameworkOfficial Hermes Labs project

Created by Hermes Labs

Published in hermes-labs-ai/zer0dex. Publisher page

64 GitHub stars

What it is

A local dual-layer memory pattern for AI agents: a compact, human-readable markdown index paired with semantic retrieval from a local vector store, queried before each message. For cross-project recall where flat memory files or vector-only RAG fall short. Local-first. Reference implementation.
— the description by Hermes Labs

AutoGineer overview, from the brain’s own files

zer0dex is a reference implementation for a local-first memory architecture designed to help AI agents manage long-term recall without overwhelming their context window. It utilizes a two-layer approach: a compact, human-editable Markdown index that provides a high-level map of stored information, and a local vector store that handles semantic retrieval of detailed memories. By providing a CLI and a loopback HTTP server, it allows developers to integrate persistent memory into their agents by querying the server before model requests. It is built for developers who need to manage growing archives of notes or project context locally, leveraging tools like Ollama, mem0, and Chroma.

How it works

Memory model: Vector store

AutoGineer overview, from the brain’s own files

The system operates through two distinct layers. The Markdown index acts as a human-readable map of projects and categories that can be kept in the agent's context. The local memory store, powered by a vector database, holds the full details of the memories. Users seed the system from markdown files, and the agent host interacts with a local HTTP server to query relevant information based on semantic meaning before generating responses.

Folders
FolderRoleFiles
.githubagent-config7
assetsattachments7
docsdocs3
srcsource-code5
teststests4
.agentsfolder1
evalfolder3

Requirements

Runtimes: Python >=3.11

Databases: Chroma

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Google Antigravity, Kiro, OpenCode, Amp, Roo Code, Cline, JetBrains Junie, Devin (ex-Windsurf)

Set it up

  1. Not scanned by AutoGineerIts dependencies are installed by pip or uv when you run it and were not scanned by AutoGineer (3 declared). https://pypi.org/project/zer0dex/

  2. Created by Hermes Labs. Published in hermes-labs-ai/zer0dex. Licence: Apache License 2.0.

Usage

AutoGineer overview, from the brain’s own files

  • Integrate memory into local AI agents
  • Manage long-term project recall
  • Seed agent memory from existing markdown notes
  • Perform semantic search over local memory stores
“Where does Project Atlas deploy?”
The agent queries the zer0dex server and retrieves the specific deployment target stored in the vector database.
“List all active project categories.”
The agent reads the human-editable Markdown index to provide a summary of current project categories.

Documentation by Hermes Labs

<div align="center">

<picture> <source media="(prefers-color-scheme: dark)" srcset="assets/zer0dex-hero-white-background.jpg"> <source media="(prefers-color-scheme: light)" srcset="assets/zer0dex-hero-black-background.jpg"> <img src="assets/zer0dex-hero-black-background.jpg" alt="zer0dex by Hermes Labs" width="100%"> </picture>

zer0dex

Give an agent long-term recall without loading every note into its prompt.

A readable Markdown index shows what the agent knows. A local vector store retrieves the details when they matter.

by Hermes Labs

PyPI · CLI reference · HTTP API

</div>

Your agent knows the project name, but the deployment decision it needs is buried in months of notes. Putting the entire archive in its context is expensive and hard to navigate; a vector store alone gives you no simple map of what's in it. zer0dex pairs a short index you can read and edit with semantic search over the underlying memories.

Try it locally

Requires Python 3.11 or 3.12 and Ollama running on your machine. Start Ollama first if it is not already serving at http://localhost:11434.

mkdir zer0dex-demo && cd zer0dex-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install zer0dex
ollama pull nomic-embed-text
ollama pull mistral:7b

printf '# Memory\n## Project Atlas\n- Deployment target: staging\n' > MEMORY.md
zer0dex check
zer0dex init
zer0dex seed --source MEMORY.md
zer0dex serve --background
zer0dex query "Where does Project Atlas deploy?"

The last command returns matching stored memories if extraction and retrieval succeeded. Run zer0dex stop when finished. The configuration and store live in the current directory (.zer0dex.json and .zer0dex/); use a disposable directory for a trial. If check fails, confirm that Ollama is running and both models were pulled before seeding.

How the two layers work

LayerWhat it gives you
Markdown indexA compact, human-editable map of projects, categories, and durable pointers. Keep this in the agent's context.
Local memory storeThe fuller details, retrieved by meaning when the agent needs them.

The CLI can seed memories from Markdown, add more text, and query a loopback HTTP server. Your agent host calls POST /query before a model request and decides which matches to include. zer0dex supplies the server and CLI; it does not install an automatic hook into your agent. A small TypeScript host adapter shows that integration point.

The default path uses local Ollama models for embeddings and memory extraction, with mem0 and Chroma for storage. You can inspect the index directly and keep the retrieval store on your machine.

When to use it

zer0dex is a fit for developers building a local, long-running agent whose notes have outgrown one MEMORY.md, but who still want a readable map of what was saved. It is a reference implementation of this two-layer pattern, currently in the 0.1.x developer-preview line. The package is not a hosted team service or a complete agent framework.

In the bundled 86-memory, 97-case evaluation, the combined approach reached 91.2% average recall and 80.0% cross-reference recall. This is one test workload; try your own notes and queries before choosing a retrieval strategy.

Go further

Apache-2.0. Hermes Labs builds agentic infrastructure for autonomous systems.

CHANGELOG.md

Changelog

All notable changes to zer0dex are documented here.

[0.1.2] - Unreleased

Added

  • zer0dex --version prints the installed package version without starting a server, opening a store, or contacting the network.

Fixed

  • zer0dex add no longer reports a successful add when the server extracts zero memories. It exits nonzero and explains how to check, query, or rephrase the text.

  • Machine-readable project metadata and the README release links align with the 0.1.2 package version.

Changed

  • CI builds the source and wheel distributions, validates them, and smoke-tests the installed wheel's CLI outside the checkout.

Compatibility

  • Additive within the 0.1.x developer-preview line: no existing command, configuration key, or HTTP route changed shape.

Evidence boundary

  • This preparation records the changes already merged to main; it does not create a tag, publish a package, or make a hosted-operation or production-readiness claim.

[0.1.1] - 2026-09-09

Added

  • zer0dex stop stops a background server that this project started. Lifecycle state is persisted in the configured storage directory, and the command signals a recorded PID only after the loopback server proves the matching per-launch token and PID.

Fixed

  • A background start that never becomes ready is cleaned up instead of leaving a half-started server behind. State that cannot be verified is preserved for inspection rather than acted on, and repeating a successful stop is a no-op.

Changed

  • Declared build metadata completed for PEP 639, chromadb>=1.5.9 required, the pinned development pytest raised to 9.1.1, and the checkout action updated. Documentation links now point at the v0.1.1 tag.

Compatibility

  • Additive within the 0.1.x developer-preview line: no existing command, configuration key, or HTTP route changed shape.

Evidence boundary

  • This release ships the documented stop lifecycle command in an installable artifact. It makes no hosted-operation, benchmark-generalization, adoption, or production-readiness claim.

[0.1.0] - 2026-08-04

Changed

  • Established 0.1.x as the first supported developer-preview compatibility line while retaining the Alpha development-status classifier.

  • Aligned the package, runtime, changelog, and user-facing documentation on version 0.1.0.

  • Declared the Ollama Python client used by the configured mem0 providers as a direct runtime dependency.

  • Reworked the README around one local first-success path, explicit Ollama requirements, integration boundaries, non-goals, and benchmark limitations.

  • Split exact CLI, HTTP, compatibility, and evaluation semantics into focused reference documentation.

Fixed

  • Updated user-scoped reads and searches for the current mem0 2.x API while retaining the legacy call shape as a compatibility fallback.

  • Made background serving wait for its own health check and reject an occupied port instead of reporting a different local server as ready.

  • Stopped content-free markdown headings from becoming extraction chunks.

  • Kept the release-published PyPI job's repository read permission alongside its trusted-publishing identity-token permission.

Compatibility

  • Existing 0.0.x commands and local configuration remain the basis of 0.1.0.

  • Migration notes will precede documented breaking changes during the 0.1.x developer-preview line.

Evidence boundary

  • This release establishes a supported developer-preview line and clarifies its documentation contract. It does not claim hosted operation, automatic agent integration, benchmark generalization, or production readiness.

[0.0.10] - 2026-08-04

Changed

  • Improved the public README, package description, keywords, project links, and Hermes Labs attribution so the local dual-layer memory pattern is easier to understand and discover.

  • Added GitHub CI, contribution and security guidance, issue templates, Dependabot configuration, and a pre-commit configuration.

  • Replaced private evaluation fixtures and workspace examples with synthetic equivalents while preserving the public evaluation mechanics.

  • Added credential-free PyPI publishing through GitHub Actions trusted publishing.

Evidence boundary

  • This release packages documentation, metadata, repository hygiene, and privacy improvements already present on main. It does not change the core memory runtime or extend the benchmark claims from 0.0.9.

[0.0.9] - 2026-03-28

Added

  • zer0dex check command — validates Ollama connectivity, required models, and Python dependencies before init/seed

  • Test suite (37 tests covering CLI, seed logic, and server endpoints)

Changed

  • README updated with CLI-based quick start (replaces direct python invocations)

[0.0.8] - 2026-03-11

Added

  • Initial public release

  • Dual-layer memory architecture (compressed index + vector store)

  • CLI with init, seed, serve, query, status, add commands

  • HTTP memory server with /query, /add, /health endpoints

  • Evaluation suite (n=97): 91.2% recall, 87% pass rate, 80% cross-reference accuracy

  • Markdown chunking and seeding pipeline

Fixed

  • Removed deprecated license classifier for setuptools PEP 639 compatibility (0.0.8 patch)

45 files · 33 not served here

Advantages

  • Provides a human-readable index that is easy to edit and maintain alongside the automated vector store. evidence: README.md
  • Reduces context window usage by separating high-level indexing from detailed semantic retrieval. evidence: README.md

Limitations

  • Does not provide an automatic hook into agent hosts; requires manual integration via the provided API. evidence: README.md
  • Not suitable for compliance or governance-heavy environments as it is a local-first developer tool. evidence: AGENTS.md

Security

Risk level: Medium risk

This brain runs

Git hooks (2)

  • .pre-commit-config.yaml: pre-commit hooks from https://github.com/pre-commit/pre-commit-hooks at v4.6.0 (contributor tooling: runs only after pre-commit install) · uses the network
  • .pre-commit-config.yaml: pre-commit hooks from https://github.com/astral-sh/ruff-pre-commit at v0.4.4 (contributor tooling: runs only after pre-commit install) · uses the network

Agent instructions that run or fetch something (2)

  • AGENTS.md: pip install -e ".[dev]"
  • AGENTS.md: python -m pytest tests/ -q
  • Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:2)
  • Medium risk: runs-git-hook-remote-exec (.pre-commit-config.yaml:9)
  • Low risk: network-instructions (.agents/skills/zer0dex/SKILL.md:5)
  • Low risk: network-instructions (AGENTS.md:20)

Attribution and licence

Created by
Hermes Labs
Declared authors
  • Rolando Bosch (declared in pyproject.toml)
  • Rolando Bosch Rodriguez (declared in CITATION.cff)
Publisher
Hermes Labs (Official Hermes Labs project)
Source
hermes-labs-ai/zer0dex · commit aae06c9
Licence
Apache License 2.0 (files served here)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Hermes Labs.

Install from source

33 of its files are not served here, so there is no ZIP. hermes-labs-ai/zer0dex at aae06c9