@needlecontext/store

Camada de persistência do NeedleContext sobre a pasta .needlc/ do seu repositório: Markdown + frontmatter, escrita atômica, índices gerados e migração automática da identidade legada.

NeedleContext

Find the context that matters.

Todo agente de código esquece. Você corrige a mesma abordagem pela terceira vez, explica a mesma regra de novo, e o AGENTS.md/CLAUDE.md do projeto vira um arquivo gigante que ninguém mantém e o próprio agente para de seguir depois de algumas centenas de linhas.

NeedleContext transforma cada correção em uma regra durável, versionada no seu repositório — com um ciclo de vida de confiança (proposta → provisória → confirmada → consolidada) e aprovação humana em cada passo. Nada é gravado sem você aceitar.

O nome vem de finding the needle in the haystack: o produto mantém a memória procedural acumulada e, para cada tarefa, encontra e entrega ao agente apenas o conhecimento realmente necessário — a agulha no palheiro.

Como fica na prática

🧠 NEEDLECONTEXT
│
├── 📚 Knowledge          conhecimento consolidado, por domínio
│   ├── backend  (5 seções)
│   └── frontend (3 seções)
│
├── 🧠 Learnings
│   ├── ⚠ Pending Review (2)      ← aguardando sua decisão
│   ├── Confirmed (12)
│   ├── Provisional (5)
│   └── ✓ Consolidated (3)        ← já promovidos para Knowledge
│
├── 🏛 Decisions          ADRs — decisões arquiteturais ratificadas
└── ⚙ Workflows           implement / bugfix / review / refactor / onboarding

Um aprendizado individual, depois de algumas confirmações:

LEARN-BACKEND-003 · Load Entity Before Business Update
Status: Confirmed · Confiança: strong · Aplicado: 8 vezes

Regra: não usar update direto no repository quando a mudança envolve
regras de negócio — sempre carregar a entidade, validar, aplicar,
persistir.

Por que confiar nisso

• Nada é gravado sem você aprovar. Toda proposta de aprendizado passa por Accept/Edit/Reject — nunca é escrita direto na memória ativa.
• A memória é sua, não de um provedor de IA. Vive em .needlc/ no seu repositório, versionada no Git, compartilhada com o time como qualquer outro arquivo de código. Trocar de Claude para Gemini para Copilot não apaga nada.
• Funciona sem a IDE aberta. O servidor MCP lê e escreve direto no disco — um agente de linha de comando funciona mesmo com nenhuma extensão rodando.
• Contexto sob medida, não um despejo. Um Context Resolver entrega só o que é relevante para a tarefa atual, dentro de um orçamento de tokens adaptado à intensidade do pedido — nunca a pasta inteira.
• Zero telemetria. Ver PRIVACY.md — nada sai da sua máquina além do que a própria ferramenta de IA que você já usa processa.
• Migração transparente. Workspaces criados com a identidade anterior (.contextforge/) são migrados automaticamente na primeira execução — nenhum aprendizado se perde.

Compatibilidade

| Agente / IDE | Como se integra | |---|---| | Claude Code (CLI / Desktop) | CLAUDE.md + skill em .claude/skills/needlecontext/ + .mcp.json | | Cursor (Desktop & CLI) | .cursor/rules/needlc.mdc + .cursor/mcp.json | | OpenCode (Desktop & CLI) | opencode.json + .opencode/skills/needlecontext/SKILL.md ou AGENTS.md | | Antigravity (IDE & CLI) | .agents/skills/needlecontext/SKILL.md + AGENTS.md + .mcp.json | | VS Code + GitHub Copilot Chat | .github/copilot-instructions.md + .vscode/mcp.json | | Terminal & CI/CD | CLI interativo (needlc init/status/review/context) | | Qualquer outro agente compatível com MCP | needlc_get_context, needlc_search, needlc_propose_learning e mais 5 ferramentas |

Instalação e Uso

1. Via CLI no Terminal (Qualquer Ambiente)

# Instalação global
npm install -g needlecontext

# Inicializar workspace e dialeto do seu agente preferido
needlc init --agent cursor
# ou: needlc init --agent opencode

# Ver status da memória procedural e pendências
needlc status

# Revisar e aprovar/editar propostas de aprendizados interativamente
needlc review

# Buscar na memória procedural (híbrida: palavra-chave + semântica)
needlc search "paginação de listas"

# Resolver contexto sob medida para uma tarefa
needlc context --task "Criar endpoint de autenticação"

# Saída JSON para agentes/CI
needlc status --json
needlc context --task "..." --json

2. MCP Server (qualquer agente compatível)

needlc-mcp --root /caminho/do/projeto
# ou sem instalar: npx -y needlc-mcp --root .

Pacotes e Arquitetura

needlecontext/
├── packages/
│   ├── core/            modelos de domínio, ciclo de vida do aprendizado, Context Resolver — zero dependências
│   ├── store/           persistência em Markdown + frontmatter sobre .needlc/
│   └── mcp-server/      servidor MCP (stdio), binário: needlc-mcp
├── apps/
│   ├── cli/             CLI dedicado para terminal (needlc)
│   └── vscode-extension/ (legado — será refinada futuramente para falar com o CLI)
└── examples/
    └── sample-project/  projeto de exemplo com .needlc/ populado

Veja docs/PROJECT_SCOPE.md para o problema e o escopo do produto, docs/ARCHITECTURE.md para a arquitetura técnica e docs/AGENT_INTEGRATION.md para como cada IDE/agente é suportado.

Desenvolvimento

pnpm install
pnpm build
pnpm test
pnpm lint

Versionamento

Este projeto segue Versionamento Semântico, com todos os pacotes do monorepo versionados em lockstep. Ver CHANGELOG.md para o histórico e a política completa.

Licença

MIT — ver LICENSE.

Projeto irmão: Universal Design Mode — resolve contexto visual; NeedleContext resolve contexto procedural.