convez.ai
SkillProdutividadeAvançado
eyupcanbodur

Agent Knowledge Hub

eyupcanbodur/agent-knowledge-hub

Monorepo de conhecimento vivo, mantido por seus agentes de código

Ver no GitHub
InicialPluginScore · de 0 a 100

Template de monorepo de conhecimento pessoal mantido por agentes de IA. Oferece skills para agentes lerem (prime), escreverem (capture) e manterem (maintain) notas estruturadas, indexadas e com linting automático. Funciona agnóstico a agentes via contrato AGENTS.md e CLIs simples.

Instalação

$npx convez-ai eyupcanbodur/agent-knowledge-hub

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Acumular descobertas de sessões de investigação com agentes de IA
  • Criar base de conhecimento consultável para múltiplos agentes (Claude Code, Copilot, Cursor, Aider)
  • Manter documentação técnica viva com linting automático e gate de qualidade

Veredito

Solução robusta e bem arquitetada para consolidar conhecimento gerado por agentes IA. Exige disciplina e bash/Node.js competente, mas entrega composto genuíno — notas que crescem, se indexam, se validam sozinhas.

README

A tradução para o português deste README ainda está na fila.

agent-knowledge-hub

A template for a personal, agent-maintained knowledge monorepo: dense, code-grounded notes that your coding agents read to prime on a topic and write to capture durable findings, so investigations compound instead of evaporating when the session ends.

Three skills drive it: read (/load-context), write (/store-to-hub), maintain (/hub-lint). Agent-agnostic by design: the contract is AGENTS.md (the open standard read natively by Claude Code, Codex, Cursor, Copilot, Gemini CLI, Aider, and most coding agents), and every operation underneath is a plain CLI any agent can run. The slash-command packaging installs into Claude Code and Codex out of the box; the skills CLI distributes it to the rest.

Read the field guide for the full why/how/workflow (also at docs/hub-guide.html locally).

How it works

At a glance:

flowchart LR
    classDef store fill:#f7f2ed,stroke:#a7988a,color:#141312
    classDef act fill:#fff,stroke:#ea2c00,color:#141312
    classDef gate fill:#fff,stroke:#02745f,color:#141312

    A["your coding agent"]:::act
    H[("the hub<br/>notes + works,<br/>indexed per sub-hub")]:::store
    MNT["weekly sweep + /hub-lint"]:::gate

    A -- "prime: /load-context" --> H
    H -- "index line, then TL;DR,<br/>then body on demand" --> A
    A -- "capture: /store-to-hub<br/>(propose, confirm, write)" --> H
    MNT -. "maintain: keeps it<br/>trustworthy" .-> H

In detail:

flowchart TB
    classDef store fill:#f7f2ed,stroke:#a7988a,color:#141312
    classDef act fill:#fff,stroke:#ea2c00,color:#141312
    classDef gate fill:#fff,stroke:#02745f,color:#141312

    A["any coding agent<br/>(reads AGENTS.md)"]:::act

    subgraph READ ["prime: /load-context &lt;topic&gt;"]
        M["match.mjs: exact keyword match<br/>over INDEX one-liners"]:::act
        FZ["empty? fzf fuzzy fallback<br/>'did you mean'"]:::act
        T1["tier 1: INDEX one-liner"]:::store
        T2["tier 2: note TL;DR"]:::store
        T3["tier 3: full note body<br/>only on demand"]:::store
        M --> FZ
        M --> T1 --> T2 --> T3
    end

    subgraph HUB ["the monorepo"]
        IDX["hubs/&lt;name&gt;/INDEX.md<br/>one line per note"]:::store
        N["notes: atomic findings<br/>TL;DR + cited sources"]:::store
        W["works/&lt;slug&gt;/: project folders<br/>reusable findings promoted to notes"]:::store
        LOG["log.md: append-only ops record"]:::store
        CH["AGENTS.md charter per sub-hub<br/>declares its scope"]:::store
    end

    subgraph WRITE ["capture: /store-to-hub"]
        C["classify.mjs: match finding<br/>against every charter"]:::act
        D{"a charter<br/>claims it?"}
        P["propose diff,<br/>wait for confirm"]:::gate
        NEW["propose a NEW sub-hub<br/>scripts/hub create"]:::act
        WR["write note + INDEX line<br/>+ log entry + lint"]:::act
        C --> D
        D -- yes --> P --> WR
        D -- no --> NEW --> P
    end

    subgraph MAINTAIN ["maintain: scheduled weekly + on demand"]
        SW["hub-maintenance.sh<br/>deterministic, ~0.3s"]:::gate
        G["hub-lint.sh gate:<br/>orphans, broken links, secrets,<br/>stale hubs, stalled works"]:::gate
        CD["citation-drift.sh:<br/>cited code changed or gone upstream?"]:::gate
        SNAP["git snapshot + notify<br/>only on regressions"]:::gate
        LLM["/hub-lint LLM pass on demand:<br/>contradictions, duplicates, stale claims"]:::act
        SW --> G --> SNAP
        SW --> CD --> SNAP
    end

    A -- "resume a topic" --> M
    T1 -.reads.-> IDX
    A -- "durable finding" --> C
    C -.reads.-> CH
    WR --> N
    WR --> IDX
    WR --> LOG
    SW -.checks.-> HUB
    LLM -.judges.-> N

The loop in one sentence: prime pulls the smallest useful slice of past knowledge (index line, then TL;DR, then body), capture routes a new finding to whichever sub-hub charter claims it (or grows a new one) behind a propose-confirm gate, and maintain runs deterministic hygiene on a schedule so the knowledge stays trustworthy without anyone remembering to check.

Get started

Use this template (or clone, any path works; install.sh records the location as HUB_ROOT), then:

cd ~/workspace/agent-knowledge-hub && ./install.sh

install.sh symlinks the skills into ~/.claude/skills/ and ~/.codex/skills/ (restart the harness after), makes the hooks runnable, and records HUB_ROOT. Optional: brew install fzf enables fuzzy retrieval (fzf subsequence matching, presented as "did you mean"; it catches doubled or dropped letters, not arbitrary edits).

The hubs/example/ sub-hub ships with two sample notes; read them for the format, then clear it and create your own:

./scripts/hub create <your-hub>

Then edit hubs/<your-hub>/AGENTS.md: one line of scope (what findings this hub claims) is enough to start.

Skills-only install (no clone): npx skills add <your-fork> --all distributes them to every supported harness via the skills CLI.

Layout

hubs/<name>/     a full hub: AGENTS.md + INDEX.md + log.md + notes (+ works/)
template/        starter scaffold for a new hub
scripts/hub      CLI: create, list
scripts/         hub-maintenance.sh (weekly sweep), citation-drift.sh
skills/          load-context, store-to-hub, hub-lint (symlinked by install.sh)
install.sh       setup
.claude/hooks/   deterministic checks: validate-note, check-index, append-log, hub-lint
docs/            note-format.md, hub-guide.html, adr/ (design rationale)

The model in five lines

  1. A note is atomic, cross-project, and findable: one INDEX line + a ## TL;DR + a code-cited body (docs/note-format.md).
  2. A work is a goal-bound project folder; reusable findings get promoted to notes.
  3. Routing is charter-driven: each sub-hub's AGENTS.md declares its scope; no fit means create a new sub-hub.
  4. Retrieval is a ladder: INDEX one-liners, then TL;DRs, then full bodies, never a bulk dump. Exact match first, fzf fuzzy fallback, agent judgment last.
  5. Maintenance is scheduled, not remembered: scripts/hub-maintenance.sh (weekly via launchd/cron) lints every hub, snapshots to git, checks citation drift, and notifies only on regressions.

Maintenance

Wire scripts/hub-maintenance.sh into launchd/cron weekly. It runs the deterministic gate over every sub-hub, auto-commits a git snapshot, and reports citation drift (notes citing code that changed or vanished upstream in your local clones). The LLM pass (/hub-lint) stays on demand.

Design rationale

docs/adr/ records why the system is shaped this way (no frontmatter, INDEX as the retrieval surface, log + git, charter-driven routing, the maintenance loop), with sources (Karpathy's LLM-wiki, Anthropic's context-engineering guidance, PARA/evergreen notes, Letta's context repositories). Read 0001 first.

Ver o original no GitHub

Bom para

Relacionados