vichar 0.1.0

Versioned Intent and Context History for Agentic Reasoning — capture the why behind AI agent decisions

VICHAR — विचार

Versioned Intent and Context History for Agentic Reasoning

VICHAR captures why AI agents make decisions — not just what they do. Every decision, open question, and task is recorded so the next session (or a different agent) starts with full context instead of zero.

---

Install

pip install vichar

Or from source:

git clone https://github.com/shivranjankolvankar/vichar
cd vichar
pip install -e .

---

Quick start

# Initialise in your project
cd my-project
vichar init

# Agents capture reasoning as they work
vichar capture "Use FastAPI over Flask" \
  --type decision \
  --author claude-code \
  --body "Flask lacks async support. FastAPI gives us OpenAPI docs for free."

# At session start — read prior context
vichar log

# Confirm an entry (human ratification)
vichar ratify abc12345

# One-line project summary
vichar status

---

Core concept: the trust gradient

Status	Meaning
proposed	Agent-written, unreviewed
ratified	Human-confirmed
closed	No longer relevant

Agents write freely. Humans decide what to trust.

---

Commands

Command	Description
vichar init	Stamp project, write agent files, inject into CLAUDE.md + .cursor/rules
vichar capture "<text>"	Capture a decision, thread, or task
vichar ratify <id>	Mark an entry as human-confirmed
vichar close <id>	Close an entry
vichar log	Show open entries (rich table)
vichar status	One-line project summary (add --json for machine output)
vichar migrate	Upgrade pre-schema entries to schema v1
vichar uninit	Remove VICHAR injection from CLAUDE.md + .cursor/rules
vichar-server	Start HTTP server on port 7474 (fallback for shell-less agents)

---

HTTP server (agent fallback)

When an agent cannot run shell commands, it can POST over HTTP instead:

vichar-server [--port 7474] [--host 127.0.0.1]

import urllib.request, json

def vichar(title, type="decision", body="", author="agent"):
    data = json.dumps({"title": title, "type": type,
                       "body": body, "author": author}).encode()
    req = urllib.request.Request(
        "http://localhost:7474/capture", data=data,
        headers={"Content-Type": "application/json"}, method="POST")
    try:
        with urllib.request.urlopen(req, timeout=2) as r:
            return json.loads(r.read())
    except Exception:
        return None  # never block on VICHAR

Server endpoints: GET / GET /status GET /log POST /capture POST /ratify POST /close

---

Agent integration

vichar init writes instruction files and injects them automatically:

• Claude Code (CLAUDE.md): injects @.vichar/CLAUDE.md import line
• Cursor (.cursor/rules): inlines the full instruction block
• Both injections are non-destructive (VICHAR START/END markers, idempotent)

The agent files tell Claude / Cursor when to capture, how to capture, and the HTTP fallback snippet.

---

What gets stored

Each entry in .vichar/entries.json has:

Field	Description
id	8-char hex identifier
type	decision / thread / task
status	proposed / ratified / closed
title	One-line summary
body	Extended reasoning (markdown)
author	claude-code / cursor / human / agent
schema	"1" (schema version)

---

Zero dependencies

VICHAR is pure Python stdlib — no rich, no colorama, no click. It works in any Python 3.8+ environment without pip install overhead.

---

License

MIT