Metadata-Version: 2.4
Name: vinod
Version: 0.2.1
Summary: A stateful personal agent that learns how you work — passive observer, episodic memory, belief formation.
Author-email: Arunabh Majumdar <arunabh.majumdar@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/motornomad/agent-vinod
Keywords: agent,memory,personalization,llm,observer,productivity
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.0

# vinod

**A stateful personal agent that learns how you work.**

Vinod passively observes your work patterns — Claude Code sessions, file changes, decisions made — and builds an episodic + semantic memory of your behavior over time. It surfaces that memory back to Claude Code automatically via MCP, so every new session picks up exactly where the last one left off.

---

## Install

```bash
pip install vinod
vinod init
```

That's the entire setup. `vinod init` scaffolds `~/.vinod/` and registers the MCP server in `~/.claude/settings.json`. Restart Claude Code and it loads your memory automatically on every session start.

---

## How it works

### The problem it solves

Every Claude Code session starts cold. You paste a handoff doc, re-explain the project, re-establish context. For a one-off task that's fine. For a project you're working on for months, it's friction that compounds.

Vinod replaces the handoff doc with a living memory. Instead of you writing "here's what we built last time," vinod has already read your episodic log and knows.

### What gets created by `vinod init`

```
~/.vinod/
├── CONTEXT.md                  # paste this into any Claude session as a fallback
├── agent/
│   ├── system_prompt.md        # Vinod's identity and role
│   └── guardrails.md           # what it will and won't do
└── memory/
    ├── episodic.jsonl          # append-only log of sessions and events
    └── semantic/
        └── beliefs.json        # stable behavioral patterns (you edit these)
```

### The MCP server

After `vinod init`, Claude Code connects to Vinod via MCP (stdio transport). Three tools are exposed:

| Tool | What it does |
|------|-------------|
| `read_memory` | Returns the last N episodic entries (default: 15) |
| `write_episode` | Appends one episodic entry from within a session |
| `get_beliefs` | Returns `beliefs.json` — your stable invariants |

Claude Code can call these tools directly. In practice: at session start Claude reads memory, reconstructs context, and asks what you want to work on. At session end it writes an episodic entry summarizing what was built.

No cloud. No API key. Everything stays in `~/.vinod/`.

---

## User journey

### Day 1

```bash
pip install vinod
vinod init
# restart Claude Code
```

Open a new Claude Code session. Claude now has access to `read_memory` and `write_episode`. On first use the log is empty — start working normally and close the session with "close session." Claude writes the first episodic entry.

### Day 2+

Open Claude Code. Claude calls `read_memory`, reads the last 15 entries, and reconstructs what you were working on. You pick up where you left off without pasting anything.

### Checking state

```bash
vinod status
```

```
Episodic entries : 23
Last 3 entries:
  [2026-04-27T01:06] agent_vinod -- Built real vinod pip package (0.2.0): vinod init...
  [2026-04-26T22:13] crosscommitvuln-bench -- Mined 3 new CVEs, dataset at 27 complete+sast
  [2026-04-26T19:17] crosscommitvuln-bench -- Completed full pipeline on all 20 CVEs
Beliefs          : 3
MCP registered   : yes
```

### Writing a manual entry

```bash
vinod log -p my-project -s "decided to switch from SQLite to Postgres" \
  -d "latency under concurrent writes was unacceptable at 10k rows" \
  --event decision_made --tags decision infra
```

Useful for recording decisions that happen outside Claude Code — architecture calls, things you read, context that would otherwise be lost.

---

## CLI reference

```
vinod init [--no-mcp]    scaffold ~/.vinod/, register MCP with Claude Code
vinod status             show episode count, last 3 entries, beliefs count, MCP state
vinod log                write a manual episodic entry (see --help for flags)
vinod mcp                start the stdio MCP server (Claude Code calls this automatically)
```

---

## Memory architecture

Vinod uses a four-type memory model:

| Type | Storage | Description |
|------|---------|-------------|
| **Episodic** | `episodic.jsonl` | Append-only log: sessions, decisions, file changes |
| **Semantic** | `beliefs.json` | Stable facts and invariants you've confirmed |
| **Procedural** | future: QLoRA weights | Behavioral patterns learned from the corpus |
| **Working** | in-context only | What Claude holds during a live session |

Right now episodic + semantic are live. Procedural memory (fine-tuning on your own corpus) is the Day 75+ phase of the roadmap.

---

## Fallback: no MCP

If you're using Claude web or a context where MCP isn't available, paste `~/.vinod/CONTEXT.md` at the start of your session. It points Claude to the episodic log and beliefs file and gives the same reconstruction instructions.

---

## Research context

Vinod is the research infrastructure for a paper on personal behavioral modeling. The core hypothesis: a model of a person (learned from longitudinal behavioral data) is qualitatively different from a memory system for a conversation. Infinite context windows solve retrieval; they don't solve personalization.

If you're a developer interested in running the observer on your own machine and contributing behavioral data to the study, reach out: arunabh.majumdar@gmail.com.

---

## Status

**0.2.0** — MCP server live, episodic + semantic memory working, `vinod init/status/log/mcp` commands functional.

Observer pipeline (passive file watching, Google Sheets integration) and belief consolidation (episodic → semantic weekly rollup) are next.
