Agent skill

Chromadb

by EliasOulkadi in EliasOulkadi/shokunin

Manage the ChromaDB vector database that stores the ecosystem's persistent memory.

MITAuto-check passedDatabases

Install Chromadb

skills CLI
$ npx skills add EliasOulkadi/shokunin --skill chromadb -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install EliasOulkadi/shokunin chromadb --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/EliasOulkadi/shokunin.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.pack/skills/chromadb .claude/skills/chromadb && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
chromadb
GitHub stars
114
Token cost
~2.2k tokens
SKILL.md length
737 words
Files
1
Skills in repo
49
Repo updated
First seen
Licence
MIT

At a glance

Manage the ChromaDB vector database that stores the ecosystem's persistent memory.

  • Works in 6 steps: Check storage status → Search stored entries → List recent entries → …
  • User asks to check memory storage
  • SKILL.md covers Workflow, Storage Details, Data Model and Session Management, plus 6 more sections
  • Calls python and pip

What it does

Chromadb is an agent skill from EliasOulkadi/shokunin. Manage the ChromaDB vector database that stores the ecosystem's persistent memory. Use when user asks to check memory storage, backup memory, search stored entries, delete entries, or reset the vector database. Do NOT use for general question answering about past sessions (use the memory skill for that).

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts. Compatibility notes: opencode

It sits in Databases, covering Vector databases, Agent memory and Embeddings. It works with Chroma and Model Context Protocol. The repository describes itself as: 職人 Shokunin 62 AI agent skills for OpenCode, Claude Code, Cursor, Windsurf. ChromaDB memory, MCP servers, declarative self-updates. Multi-model, open source, zero cost. The licence is MIT.

When your agent uses it

  • User asks to check memory storage
  • Search stored entries
  • Reset the vector database
  • General question answering about past sessions (use the memory skill for that)

Example prompts

  • “/chromadb”

Requirements

  • Python 3
  • Compatibility (from SKILL.md): opencode

Workflow steps

6 steps, taken from the step headings in SKILL.md.

  1. Check storage status
  2. Search stored entries
  3. List recent entries
  4. Backup the database
  5. Delete entries by session prefix
  6. Full reset (requires confirmation)

What it can do on your machine

Read from SKILL.md and the folder at commit 4c68e5b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • python
    • pip

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use pip, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    opencode

    From compatibility in the SKILL.md frontmatter.

Context cost

Chromadb loads about 2.2k tokens when it runs. Until then it costs about 79 tokens; SKILL.md has 737 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~79
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from EliasOulkadi/shokunin at commit 4c68e5b, republished under its MIT licence (© EliasOulkadi). 737 words, ~2,218 tokens.

Download SKILL.mdSave it as .claude/skills/chromadb/SKILL.md (or your agent's skills folder).
name
chromadb
description
Manage the ChromaDB vector database that stores the ecosystem's persistent memory. Use when user asks to check memory storage, backup memory, search stored entries, delete entries, or reset the vector database. Do NOT use for general question answering about past sessions (use the memory skill for that).
compatibility
opencode
triggers
manage memory, memory status, memory backup, memory delete, memory reset, ChromaDB status, check storage, delete entry, backup database, reset database
negatives
search memory, query context, save context, verify file, context recall, remember past
license
MIT
metadata.workflow
administration
metadata.audience
developers
metadata.version
4.2.2

chromadb · Memory Storage

ChromaDB is the vector database that powers Shokunin's persistent AI memory. It stores embeddings for semantic search across sessions. Built on SQLite with an ONNX embedding model for local-first, offline-capable operation.

Workflow

Step 1: Check storage status
powershell
python ~/.shokunin/scripts/chroma-helper.py count

Output: total entries, collection count, disk size on disk, last write timestamp.

powershell
python ~/.shokunin/scripts/chroma-helper.py stats

Output: entries per type (decision, file, command, checkpoint, session_end), per project, per date range.

Step 2: Search stored entries
powershell
python ~/.shokunin/scripts/chroma-helper.py search "query text" "project-name" 10

Searches via vector similarity + BM25 keyword hybrid. Results sorted by relevance with metadata attached.

powershell
python ~/.shokunin/scripts/chroma-helper.py search "error handling" "" 20 --type decision

Filter by entry type. Leave project empty to search all projects.

Step 3: List recent entries
powershell
python ~/.shokunin/scripts/chroma-helper.py recent 10

Shows the 10 most recently inserted entries across all projects. Use for quick audit.

powershell
python ~/.shokunin/scripts/chroma-helper.py recent 50 --project myproject

Filter recent entries to a specific project.

Step 4: Backup the database
powershell
$backupDir = "$env:USERPROFILE\.shokunin\backups\chroma-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
New-Item -ItemType Directory -Path $backupDir -Force | Out-Null
Compress-Archive -Path "$env:USERPROFILE\.shokunin\memory\chroma_db" -DestinationPath "$backupDir\chroma_db.zip" -Force

Also back up session logs:

powershell
Compress-Archive -Path "$env:USERPROFILE\.shokunin\memory\sessions" -DestinationPath "$backupDir\sessions.zip" -Force

Verify backup integrity:

powershell
Add-Type -AssemblyName System.IO.Compression.FileSystem
[System.IO.Compression.ZipFile]::OpenRead("$backupDir\chroma_db.zip").Entries.Count
Step 5: Delete entries by session prefix
powershell
python ~/.shokunin/scripts/chroma-helper.py delete "session-prefix"

Deletes all entries whose session_id starts with the given prefix. Non-reversible. Backup first.

powershell
python ~/.shokunin/scripts/chroma-helper.py delete --project "old-project"

Delete all entries for a project. Useful when archiving finished projects.

Step 6: Full reset (requires confirmation)
powershell
Remove-Item -Recurse -Force "$env:USERPROFILE\.shokunin\memory\chroma_db"
# Restart MCP server to recreate the database

The database is auto-created on next MCP server startup. All sessions, embeddings, and metadata are permanently lost. Only do this when migrating or recovering from corruption.

Storage Details

LocationPurpose
~/.shokunin/memory/chroma_db/ChromaDB persistent files (SQLite + embeddings)
~/.shokunin/memory/sessions/Per-session JSONL logs and Markdown summaries
~/.shokunin/memory/mcp-server.logMCP server log file (auto-rotated at 5MB)
~/.shokunin/backups/Timestamped backup archives
~/.shokunin/scripts/chroma-helper.pyCLI management script

Data Model

ConceptDescription
CollectionChromaDB namespace for embeddings (one per project by default)
EmbeddingVector representation of text for semantic similarity search
MetadataKey-value pairs attached to each entry (type, tags, project, session_id, timestamp)
DocumentThe raw text content stored alongside the embedding
BM25 IndexSparse retrieval index that complements vector search (keyword matching)
Result FusionMerges vector + BM25 results for higher recall (reciprocal rank fusion)
Entry Typesdecision, file, command, preference, checkpoint, session_end, general

Session Management

CommandDescription
python ~/.shokunin/scripts/chroma-helper.py session list [N]List recent sessions with metadata
python ~/.shokunin/scripts/chroma-helper.py session continue <id>Load full session context
python ~/.shokunin/scripts/chroma-helper.py session summary <id>Show session summary
python ~/.shokunin/scripts/chroma-helper.py save "<text>" "<id>" "<type>" "<tags>" "<project>"Save entry

Error Handling

ErrorCauseFix
ChromaDB not foundPackage not installedpip install chromadb
Collection emptyNo data stored yetNormal on first use. Start storing context.
Slow first queryDownloading ONNX modelFirst query downloads ~79MB. Subsequent queries are instant.
Permission deniedFile locked by another processClose other MCP server instances
Corrupted databaseUnexpected shutdown or disk fullRestore from backup or delete and let the system reinitialize
Memory usage highLarge collection over timeRun consolidate_memories to merge old entries
Embedding dimension mismatchModel was upgraded or changedDelete chroma_db/ and reindex from session logs
UUID collisionRace condition in parallel writesChromaDB handles this internally; retry the insert
SQLite disk I/O errorFilesystem full or read-onlyFree disk space (need ~2x DB size); check permissions
Show full SKILL.md (260 more words)Show less

Anti-Patterns

PatternProblemFix
Deleting chroma_db/ without backupPermanent data lossAlways backup first (Step 4)
Running multiple MCP serversDatabase locked, data corruptionOnly one MCP server instance at a time
Manual SQL manipulationBreaks ChromaDB invariantsUse chroma-helper.py CLI or MCP tools only
Ignoring session_list filtersSeeing test/healthcheck entriessession_list automatically filters noise
Storing extremely large textBloating vector indexChromaDB truncates at 500 chars
Never consolidatingDatabase grows indefinitelyRun consolidate_memories periodically
Skipping backupsNo recovery from disk failureWeekly backup is configured via Task Scheduler
Using raw SQLite instead of ChromaDB APISchema and index corruptionAlways go through ChromaDB's Python client
Searching without project filter for broad queriesToo many irrelevant resultsAlways filter by project when context is known

Automation

Weekly backup every Sunday via Windows Task Scheduler (pre-configured). Manual backup via Step 4 above. Logs auto-rotate at 5MB to prevent unbounded growth. The consolidate_memories function runs automatically when entry count exceeds 10,000 per project.

Recovery Procedures

Restore from backup
powershell
$backup = Get-ChildItem "$env:USERPROFILE\.shokunin\backups" -Directory | Sort-Object LastWriteTime -Descending | Select-Object -First 1
Expand-Archive -Path "$backup\chroma_db.zip" -DestinationPath "$env:USERPROFILE\.shokunin\memory\chroma_db" -Force
Rebuild from session logs

If backups are unavailable, session JSONL logs contain all raw text. Replay them:

powershell
python ~/.shokunin/scripts/chroma-helper.py rebuild --from-sessions
Verify database health
powershell
python ~/.shokunin/scripts/chroma-helper.py verify

Checks: SQLite integrity, embedding count vs document count, orphan metadata, collection schema version.

Checklist

  • ChromaDB client initialized lazily (not at import time)
  • Collection name sanitized (alphanumeric + hyphens only)
  • Embedding dimension matches between writes and queries
  • Backups configured before destructive operations (delete/reset)
  • Search results validated — empty results handled gracefully

Sources

  • ChromaDB documentation (docs.trychroma.com)
  • OpenAI text-embedding-ada-002 (or local ONNX embedder)
  • SQLite documentation (sqlite.org)
  • DuckDB (ChromaDB's internal query engine)
  • MCP Protocol (modelcontextprotocol.io)
  • Shokunin Memory System Architecture (ARCHITECTURE.md)

© EliasOulkadi, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .pack/skills/chromadb of EliasOulkadi/shokunin.

Open the folder on GitHubat commit 4c68e5b

Compare with similar skills

Chromadb next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Chromadb compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Chromadb this skillEliasOulkadi/shokunin114—~2.2kAutomated safety check: PassMIT
Agent Memory Systemsomer-metin/skills-for-antigravity163—~731Automated safety check: PassApache-2.0
Memoryharperreed/dotfiles334—~484Automated safety check: PassNone
Codebase Managementgiancarloerra/SocratiCode3.3k1 repos~1.8kAutomated safety check: PassAGPL-3.0
Codebase Explorationgiancarloerra/SocratiCode3.3k1 repos~1.5kAutomated safety check: PassAGPL-3.0
Ogham Recallogham-mcp/ogham-mcp115—~1kAutomated safety check: PassMIT

Similar skills

  • Agent Memory Systems

    omer-metin/skills-for-antigravity

    Memory is the cornerstone of intelligent agents. An agent skill from omer-metin/skills-for-antigravity.

    163 GitHub stars~731 tokensUpdated 8 mo ago
    Agent WorkflowsAuto-check passed
  • Memory

    harperreed/dotfiles

    Semantic memory and context - store and retrieve information with embeddings for similarity search.

    334 GitHub stars~484 tokensUpdated 8 days ago
    AI & LLM EngineeringAuto-check passed
  • Codebase Management

    giancarloerra/SocratiCode

    Set up, index, and manage SocratiCode codebase indexing. An agent skill from giancarloerra/SocratiCode.

    3.3k GitHub starsUsed in 1 repo~1.8k tokens
    AI & LLM EngineeringAuto-check passed
  • Codebase Exploration

    giancarloerra/SocratiCode

    Explore and understand codebases using SocratiCode semantic search, dependency graphs, and context artifacts.

    3.3k GitHub starsUsed in 1 repo~1.5k tokens
    DatabasesAuto-check passed
  • Ogham Recall

    ogham-mcp/ogham-mcp

    Smart retrieval from Ogham shared memory. An agent skill from ogham-mcp/ogham-mcp.

    115 GitHub stars~1k tokensUpdated 11 days ago
    Agent WorkflowsAuto-check passed
  • Chroma Vector Database

    Orchestra-Research/AI-Research-SKILLs

    Shows how to store documents and embeddings in Chroma, query them by similarity with metadata filters, and persist them to disk for RAG and semantic search projects.

    13k GitHub starsUsed in 7 repos~2.3k tokens
    AI & LLM EngineeringAuto-check passed

More from EliasOulkadi/shokunin

All 49 skills in this repo
  • CI CD

    EliasOulkadi/shokunin

    Design CI/CD pipelines for GitHub Actions, GitLab CI, and CircleCI with matrix builds, test sharding, caching, Docker layer caching, OIDC auth, deployment strategies (rolling, blue-green, canary)…

    114 GitHub stars~3.4k tokensUpdated 6 days ago
    Auto-check: notes
  • Component Forge

    EliasOulkadi/shokunin

    Build production-grade components for React, Vue 3, and Svelte 5 with all states (loading, empty, error, success, idle), TypeScript strict, WCAG 2.2 accessibility, server components (RSC), and…

    114 GitHub stars~3.6k tokensUpdated 6 days ago
    Auto-check: notes
  • DB Admin

    EliasOulkadi/shokunin

    PostgreSQL database administration — backup/restore (pgdump, PITR, WAL archiving), health monitoring (connections, bloat, cache hit ratio, dead tuples), connection pooling (PgBouncer), replication…

    114 GitHub stars~2k tokensUpdated 6 days ago
    Auto-check: notes
  • DB Sculptor

    EliasOulkadi/shokunin

    Design database schemas with Prisma/Drizzle, PostgreSQL index strategy (B-tree, GIN, GiST, BRIN, Hash), query optimization (EXPLAIN ANALYZE), migration safety (expand/contract, zero-downtime), and…

    114 GitHub stars~3.1k tokensUpdated 6 days ago
    Auto-check: notes
  • Docker

    EliasOulkadi/shokunin

    Optimize Docker images with multi-stage builds, distroless bases, BuildKit cache mounts, multi-arch builds, compose watch, security hardening (non-root, seccomp, capabilities drop), and…

    114 GitHub stars~3.8k tokensUpdated 6 days ago
    Auto-check: notes
  • Error Handler

    EliasOulkadi/shokunin

    Design error handling, structured logging, and observability with OpenTelemetry (traces, metrics, logs), error classification, recovery patterns (retry with jitter, circuit breaker, bulkhead…

    114 GitHub stars~3.6k tokensUpdated 6 days ago
    Auto-check: notes

Questions about Chromadb

What does Chromadb do?

Manage the ChromaDB vector database that stores the ecosystem's persistent memory. Chromadb is an agent skill from EliasOulkadi/shokunin. Manage the ChromaDB vector database that stores the ecosystem's persistent memory.

When should I use Chromadb?

Chromadb fits situations like: user asks to check memory storage; search stored entries; reset the vector database; general question answering about past sessions (use the memory skill for that).

How do I install Chromadb in Claude Code?

Run `npx skills add EliasOulkadi/shokunin --skill chromadb -a claude-code`. Or copy the skill folder (.pack/skills/chromadb in EliasOulkadi/shokunin) into .claude/skills/chromadb in your project. Claude Code loads it when a task matches its description.

How do I install Chromadb in Codex?

Run `npx skills add EliasOulkadi/shokunin --skill chromadb -a codex`. Or copy the skill folder (.pack/skills/chromadb in EliasOulkadi/shokunin) into .agents/skills/chromadb in your project. Codex loads it when a task matches its description.

Can I use Chromadb in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add EliasOulkadi/shokunin --skill chromadb -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/chromadb, .gemini/skills/chromadb, .github/skills/chromadb and .opencode/skills/chromadb in your project.

What does Chromadb need to run?

Going by SKILL.md and its folder, Chromadb needs the command-line tools its instructions call (python and pip). Our summary lists: Python 3. Compatibility (from SKILL.md): opencode.

Does Chromadb access the network?

SKILL.md contains no URLs. Its commands use pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Chromadb safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Chromadb use?

Chromadb is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Chromadb use?

About 2.2k tokens (SKILL.md is roughly 8.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Chromadb?

Skills that share tags, products or a category with Chromadb: Agent Memory Systems (omer-metin/skills-for-antigravity, 163 stars), Memory (harperreed/dotfiles, 334 stars), Codebase Management (giancarloerra/SocratiCode, 3.3k stars) and Codebase Exploration (giancarloerra/SocratiCode, 3.3k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Chromadb?

EliasOulkadi (a GitHub user) maintains it in EliasOulkadi/shokunin, which has 114 GitHub stars. The repository holds 49 skills in this directory. The repository was last updated on October 5, 2026.

Source: EliasOulkadi/shokunin on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.