expcap

name: expcap description: Use agent-experience-capitalization as a project-owned, team-shareable engineering memory layer for coding agents. Use it to activate prior experience before work, save reusable lessons after work, inspect save/get/log health, and diagnose Milvus-centric retrieval.

Positioning

This skill is the recommended entrypoint. The expcap CLI is the execution layer behind it.

expcap does not compete with personal memory in Codex, Claude Code, or other agents. It focuses on project-level, team-level, and organization-level engineering experience assets: shareable, reviewable, and deliverable with the codebase.

Default runtime profile:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap"

Assets remain project-owned even when stored outside the project directory.
Runtime data goes under $HOME/.expcap/projects/... by default.
Milvus is the core semantic retrieval layer.
SQLite is a lightweight state index, activation log, and fallback path.
Activation returns sourced candidates; the current agent decides whether each asset applies to the task.
New chat should still run expcap auto-start even for projects marked inactive; the label is mainly for reporting and coverage analysis.

When To Use

Before coding work, activate relevant project experience.
After completed work, save reusable lessons, rules, patterns, or context.
When checking usage, activation feedback, asset temperature, review status, candidate queues, or new assets.
When validating the save/get/log loop.
When diagnosing Milvus, SQLite, centralized storage, or shared backend configuration.
When installing project-owned/team-shareable memory into another repository.

Default Commands

Start a task by activating experience:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap auto-start --task "<task summary>" --workspace "$PWD"

During a task, run event-driven delta recall only when the conversation changes:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap progressive-recall --task "<task summary>" --workspace "$PWD" --message "<new error/file/phase/topic signal>"

When a real task confirms whether the activation helped, record it:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap feedback --workspace "$PWD" --activation-id "<activation id>" --help-signal supported_strong

Finish a task by saving experience:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap auto-finish --task "<task summary>" --workspace "$PWD" --verification-status passed --result-status success

Check runtime health:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap status --workspace "$PWD"
EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap doctor --workspace "$PWD"
EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap dashboard --workspace "$PWD"

Sync the Milvus retrieval index:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap sync-milvus --workspace "$PWD" --include-shared

Benchmark Milvus retrieval quality:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap benchmark-milvus --workspace "$PWD" --sample-size 5 --limit 3 --include-shared

benchmark-milvus 会先同步当前 embedding profile 对应的 Milvus index，避免 profile 切换或 fallback 被误判成召回失败。

Optional real embedding provider:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" EXPCAP_EMBEDDING_PROVIDER=openai OPENAI_API_KEY="..." EXPCAP_OPENAI_EMBEDDING_MODEL=text-embedding-3-small EXPCAP_OPENAI_EMBEDDING_DIM=128 expcap benchmark-milvus --workspace "$PWD"

If the OpenAI API key is missing, expcap should fall back to hash and expose that fallback in retrieval_backends.milvus.embedding.

Milvus Lite DB files are namespaced by embedding profile so provider/dimension changes do not mix vectors in one local index.

Hosted Milvus can be used by setting:

EXPCAP_RETRIEVAL_BACKEND=milvus EXPCAP_RETRIEVAL_INDEX_URI=https://milvus.example.com EXPCAP_RETRIEVAL_INDEX_TOKEN="..." expcap doctor --workspace "$PWD" --deep-retrieval-check

Use EXPCAP_MILVUS_DB_NAME and EXPCAP_MILVUS_COLLECTION when the hosted Milvus deployment requires a specific database or collection name.

Install into another project:

EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap install-project --workspace /path/to/project
EXPCAP_STORAGE_PROFILE=user-cache EXPCAP_HOME="$HOME/.expcap" expcap install-project --workspace /path/to/project --project-status inactive

Operating Rules

Run auto-start before substantive analysis, edits, or verification.
Use progressive-recall only for meaningful new signals: new errors, new files/modules, topic drift, or phase changes. Do not run it on every turn.
Use feedback after a real validation result so linked assets can refresh their temperature and review status.
Treat active / inactive as a reporting label. If a new chat starts in the project, auto-start should still run by default.
If experience is activated, summarize what matched, why it matched, and how it affects the current strategy.
Run auto-finish after a coherent task is complete or a stable lesson has emerged.
Do not save when the task is unresolved, the conclusion is unstable, the change is only a temporary workaround, verification is missing, or the user asked not to record.
Treat repository-specific experience as project scope by default.
Promote to cross-project only after the lesson has been validated across more than one project.
Store project conventions, historical decisions, and directory constraints as context or rule assets when they guide future work.
Do not make users memorize commands. Run the workflow for them and report the result, source, and risk.

Diagnostics

Watch these status fields:

activation_feedback_summary: whether activations helped.
feedback_cleanup: stale unresolved activations that were auto-closed as unclear.
candidate_review_queue: candidates waiting for review.
asset_effectiveness_summary: asset temperature and review status.
retrieval_backends: Milvus core retrieval readiness and SQLite lightweight index health.
dashboard: local read-only HTML view of assets, retrieval contribution, quality signals, write frequency, and candidate review queues.
project_activity: whether the current workspace is active for default reporting and coverage analysis.
backend_configuration: active local, user-cache, shared, or hybrid profile.

If Milvus Lite is locked or unavailable, the runtime may degrade to JSON/SQLite so work can continue. Treat that as reduced retrieval quality and prioritize Milvus recovery for meaningful testing.