Knowcards

Local-first durable facts for coding agents, fetched as trusted memory

"A computer program is said to learn from experience E with respect to some class of tasks T and performance measure P, if its performance at tasks in T, as measured by P, improves with experience E." — Tom Mitchell

Alpha — this package is early. The API and host hook shapes may change.

Star this repo to stay in the loop as we ship.

npm version npm GitHub stars Node Claude Code Codex Cursor license

Highlights · Quick start · Agent protocol · How it works · Docs

---

Highlights

Knowcards = project-local markdown facts + automatic fetch/reflect on supported hosts.

• Filesystem-first — cards are plain markdown under .agents/knowledge_cards. No DB, no vectors.
• Trusted memory — hits are preferred over rediscovery or a conflicting README unless the card is stale.
• Host edges — install wires Claude Code / Codex / Cursor hooks and a Pi extension; CLI and MCP remain for manual use.

Coding agents forget between sessions. They re-grep the tree, re-read the README, and still miss the constraint that mattered last time. That wastes tokens and wall clock — and fails when the workspace is wrong.

Knowcards keeps those facts as local cards and fetches them again. The agent prefers the card unless new evidence shows it is wrong.

---

Quick start

# Install automatic fetch + reflect hooks (pick your host)
npx knowcards install cursor
npx knowcards install claude-code
npx knowcards install codex
npx knowcards install pi

# Write a durable fact (creates dirs if needed)
npx knowcards propose --title "JWT auth header" \
  "JWTs go in the Authorization header"

# Change or remove a card
npx knowcards update jwt-auth-header --title "JWT auth header" \
  "JWTs go in the Authorization header as Bearer"
npx knowcards delete jwt-auth-header

# Search the local card library
npx knowcards query jwt

# Show notebook paths and card counts
npx knowcards status

# MCP stdio server (for host config below)
npx knowcards mcp

Cards live at .agents/knowledge_cards/<notebook-id>/*.md:

---
title: Payment amounts are integer cents
---

Amounts are stored as integer cents; never use floating point for money.

Optional: put a custom reflection prompt in project-root REFLECT.md. If missing, knowcards uses the packaged default.

MCP

{
  "mcpServers": {
    "knowledge-cards": {
      "command": "npx",
      "args": ["knowcards", "mcp"]
    }
  }
}

Install the knowcards skill (or equivalent host instructions) so the agent can still query/propose mid-session without hooks.

---

Agent protocol

With hooks installed, fetch and end-of-session reflect run automatically. The manual loop still works:

1. Before acting — npx knowcards query "<keywords>" (or the MCP tool). Skip only for routine edits in code you already hold.
2. Apply hits — Prefer card facts. Verify against the repo when a card may be old.
3. Propose at end — Write durable facts from the outcome (what proved true), not the path you took. One atomic fact per card.

Do not propose plans or unverified guesses. Near-duplicates are fine; bookkeeping is separate.

---

How it works

A typical ReAct agent takes a user query, then reasons and acts in a loop, then gives a final answer. It does not read or write durable memory.

flowchart TB
  Q[User query] --> R[Reason]
  R -->|act| A[Act]
  A -->|observation| R
  R -->|done| F[Final answer]

Knowcards wraps that loop. After the user query, fetch asks memory for relevant chunks through retrieve. After the final answer, reflect writes new facts through save. Memory is a black box in this view.

flowchart LR
  subgraph H["Harness loop"]
    direction TB
    HQ[User query] --> HF[fetch]
    HF --> HR[Reason]
    HR -->|act| HA[Act]
    HA -->|observation| HR
    HR -->|done| HFA[Final answer]
    HFA --> HREF[reflect]
  end

  subgraph M["Memory (black box)"]
    direction TB
    MR[retrieve]
    MS[save]
  end

  HF -->|ask| MR
  MR -->|relevant chunks| HF
  HREF -->|new facts| MS

The install command wires Claude Code, Codex, or Cursor hooks, or a Pi extension. A prompt retrieves matching cards (MiniSearch) and fetches titles into context. Use query or MCP for the full text. Reflect continues the same session so the agent can propose: Stop on Claude Code / Cursor / Codex, session_shutdown on Pi. Cards are markdown under .agents/knowledge_cards. Knowcards does not bundle an LLM.

• src/memory/ — save, store, retrieve
• src/harness/ — fetch + reflect
• src/adapters/ — host hook envelopes
• src/mcp/ and src/cli/ — memory API; install is adapter wiring

---

Docs

Document	Contents
CONTRIBUTING.md	Setup, Harbor evals, how to contribute
SECURITY.md	How to report a vulnerability
AGENTS.md	Conventions for agents working in this repo
eval/README.md	Harbor A/B (bare Pi vs extension + CLI)
skills/knowcards/SKILL.md	Agent skill: when to query / propose

License

MIT. See LICENSE.

Author: mbajaj_