Metadata-Version: 2.4
Name: vinod
Version: 0.5.1
Summary: A stateful personal agent with episodic memory for Claude Code.
Author-email: Arunabh Majumdar <arunabh.majumdar@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/motornomad/agent_vinod
Project-URL: Repository, https://github.com/motornomad/agent_vinod
Project-URL: Bug Tracker, https://github.com/motornomad/agent_vinod/issues
Keywords: agent,memory,personalization,llm,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
Requires-Dist: anthropic>=0.40.0

# vinod

**Persistent memory for Claude Code. Every session picks up where the last one left off.**

No context pasting. No handoff docs. Vinod stores what you built, what you decided, and what's next — and surfaces it automatically at the start of every Claude Code session.

GitHub: [motornomad/agent_vinod](https://github.com/motornomad/agent_vinod)

---

## Install

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

> **Install globally, not inside a venv.** Vinod runs as a background hook every time Claude Code starts — it needs to be on your system PATH, not scoped to a project environment.

**Windows:** If `vinod` is not found after install, your Python Scripts folder may not be in PATH. Fix it in PowerShell:

```powershell
$p = python -c "import sys; print(sys.prefix + '\Scripts')"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$p", "User")
```

Then open a new terminal and run `vinod init` again. Git Bash users: add `export PATH="$PATH:/c/Users/<your-username>/AppData/Roaming/Python/Python3XX/Scripts"` to `~/.bashrc` and run `source ~/.bashrc`.

Restart Claude Code. That's it.

---

## What happens after `vinod init`

`vinod init` does four things:

1. Scaffolds `~/.vinod/` — episodic log, beliefs file, agent identity files
2. Writes `~/.claude/CLAUDE.md` — tells Claude how to use the memory
3. Registers a **UserPromptSubmit hook** (`vinod session-start`) — injects your recent memory into every new session automatically
4. Registers a **Stop hook** (`vinod session-end`) — summarises and saves the session when Claude Code closes

Both hooks are wired into `~/.claude/settings.json`. Claude Code runs them for you — no manual steps.

---

## How it works

### Session start (automatic)

When you open Claude Code and send your first message, the `vinod session-start` hook fires before Claude responds. It reads your last 15 episodic entries and any active beliefs, then injects a briefing into the conversation context. Claude sees this and does two things:

1. Summarises what was last worked on in 2–3 sentences
2. Asks: "Want to continue there, or work on something else?"

You didn't paste anything. Claude already knows.

### Session end (automatic)

When Claude Code stops (or you close the session), the `vinod session-end` hook fires. It parses the session transcript, summarises what was built or decided, and appends an episodic entry to `~/.vinod/memory/episodic.jsonl`.

If you have an Anthropic API key configured (`vinod config set-api-key <key>`), summaries are generated by Claude Haiku with a cached system prompt. Otherwise, a rule-based summariser runs as a fallback.

---

## Memory layout

```
~/.vinod/
├── CONTEXT.md                  # fallback: paste into any session without hook support
├── agent/
│   ├── system_prompt.md        # Claude's identity and role (edit to personalise)
│   └── guardrails.md           # hard limits (edit to add constraints)
└── memory/
    ├── episodic.jsonl          # append-only log of sessions and decisions
    ├── consolidation_state.json # last consolidation run metadata
    └── semantic/
        └── beliefs.json        # stable invariants that override episodic memory
```

### Episodic vs semantic

**Episodic** memory is the rolling log. Every session writes an entry: what project, what was built, which files were touched. The last 15 entries are injected at session start.

**Semantic** memory (`beliefs.json`) is for stable facts that should always hold — architectural constraints, research invariants, hard decisions. Beliefs override episodic when they conflict. You can edit this file directly, or let `vinod consolidate` promote patterns automatically.

---

## Consolidation: episodic → semantic

After you have a few weeks of sessions, run:

```bash
vinod consolidate
```

Vinod reads your recent episodic log, calls Claude Haiku, and promotes recurring patterns into `beliefs.json` automatically. Beliefs are deduplicated and confidence-scored.

```bash
vinod consolidate --dry-run        # preview without writing
vinod consolidate --days 60        # read 60 days instead of 30
```

Requires an API key (`vinod config set-api-key sk-ant-...`). You can also schedule this via cron — e.g., weekly.

---

## MCP tools (available inside sessions)

Claude Code connects to Vinod via MCP (stdio transport, registered by `vinod init`):

| Tool | What it does |
|------|-------------|
| `read_memory` | Returns the last N episodic entries |
| `write_episode` | Writes a richer episodic entry than the hook would produce |
| `get_beliefs` | Returns `beliefs.json` |
| `search_episodes` | Filters episodic entries by project name and/or tags |
| `consolidate` | Triggers episodic → semantic promotion (requires API key) |
| `update_belief` | Adjusts a belief's confidence or retires it |

In practice the basic tools are called automatically by the hooks, but you can invoke any of them explicitly — e.g., say "close session" to trigger a detailed `write_episode` call, or "consolidate my memory" to promote today's patterns into beliefs.

---

## CLI reference

```
vinod init [--no-mcp]              scaffold ~/.vinod/, register MCP and both hooks
vinod status                       episode count, recent entries, belief summary, consolidation state
vinod log -p <proj> -s <msg>       write a manual episodic entry
vinod consolidate [--days N]       promote episodic patterns into beliefs via Claude API
  [--dry-run]
vinod config set-api-key <key>     store an Anthropic key for LLM-based summaries and consolidation
vinod config show                  show current config
vinod uninstall                    remove ~/.vinod/, deregister hooks and MCP from settings.json
vinod mcp                          start the MCP server (Claude Code calls this; you don't need to)
```

---

## Day-by-day experience

**Day 1:** `pip install vinod && vinod init`, restart Claude Code. First session starts cold (empty log). Work normally. At end, say "close session" — Claude writes a detailed first entry.

**Day 2+:** Open Claude Code, send any message. Vinod injects your memory. Claude briefs you on yesterday's work and asks what's next. You answer. No context pasting required.

**After a few weeks:** Run `vinod consolidate`. Stable patterns from your session history become beliefs that persist across all future sessions.

**Checking state:**

```bash
vinod status
```
```
Episodic entries : 31
Last 3 entries:
  [2026-04-27T21:59] my-project -- Added auth middleware; deployed to staging
  [2026-04-27T21:38] my-project -- Wired logging pipeline; fixed retry logic
  [2026-04-27T04:29] code-server -- Google OAuth + HTTPS proxy live
Beliefs          : 5 total, 5 active
  [92%] User works primarily on my-project and code-server in parallel
  [85%] Auth middleware is the current critical path
  [78%] Deployments go to staging first, then prod after review
Last consolidate : 2026-04-28T02:00  (+3 beliefs from 28 episodes)
MCP registered   : yes
```

---

## Optional: LLM-based session summaries

By default, session summaries are generated by a rule-based parser (fast, no API key needed). For richer summaries and consolidation support:

```bash
vinod config set-api-key sk-ant-...
```

Vinod will use Claude Haiku (cached system prompt) to summarise each session and to run consolidation. Falls back to rule-based if the API call fails.

---

## Status

**0.5.0** — Consolidation: `vinod consolidate` promotes episodic patterns into semantic beliefs via Claude API. New MCP tools: `search_episodes`, `consolidate`, `update_belief`. Richer `vinod status` with belief confidence summary and last consolidation state. Fixed beliefs display bug (beliefs were silently dropped if schema used `fact` field instead of `summary`).

**0.4.11** — Hook-based session start and end. `vinod init` registers both hooks automatically. No context pasting required. LLM summarisation with Haiku (optional). `vinod config` for API key management. `vinod uninstall` to cleanly remove. Windows fixes.

---

<img src="https://raw.githubusercontent.com/motornomad/agent_vinod/master/assets/agent_vinod.png" width="300"/>
