backstory-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{backstory_cli-0.2.0 → backstory_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backstory-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Every AI-assisted commit has a backstory. Never lose it again.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
 # Backstory
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
-[![OKF](https://img.shields.io/badge/knowledge%20format-OKF-orange)](https://cloud.google.com/blog/products/data-analytics)
+[![Google's OKF](https://img.shields.io/badge/knowledge%20format-OKF-orange)](https://cloud.google.com/blog/products/data-analytics)
 
 **Git shows what changed. Backstory shows why.**
 
@@ -25,14 +25,15 @@ markdown, and links it to Git commits so you can retrieve the *why* later.
 
 - Local-first by default — everything stays in your repo
 - Recovers *why* a decision was made, after the codebase has moved on
-- Stores durable session memory as OKF markdown — human-readable,
+- Stores durable session memory as Google's OKF markdown — human-readable,
   Git-friendly, and agent-friendly
 - Links memory to Git commits so the reasoning stays searchable
 - Detects contradictions when later changes reverse earlier decisions
 - Extracts decisions, risks, and follow-ups — not raw chat logs
 
 Backstory is not an AI coding agent. It is the memory layer around
-AI-assisted coding.
+AI-assisted coding — useful whether you're building alone or shipping
+across enterprise teams.
 
 ## Example
 
@@ -155,22 +156,62 @@ The capture and retrieval pipeline has four steps:
 
 Git stays the linkage layer. Backstory stores the reasoning.
 
-## Quick Start
+## Prerequisites
 
-Install the PyPI package:
+- **Python 3.11+** — Backstory requires Python 3.11 or newer.
+- **pip or pipx** — Either package manager works. On fresh machines, `pipx` is
+  recommended because it installs Backstory in its own isolated environment
+  without needing a separate virtual environment.
+- **Git** — Backstory stores session memory inside a Git repository and links
+  it to commits.
+
+## Install
+
+Install directly from the repository:
+
+```bash
+# Using pip (system-wide or in a virtual environment)
+python3 -m pip install git+https://github.com/arpitkath/backstory.git
+
+# Using pipx (isolated, recommended for fresh machines)
+pipx install git+https://github.com/arpitkath/backstory.git
+```
+
+Or install the PyPI package:
 
 ```bash
 python -m pip install backstory-cli
 ```
 
-The installed command is still:
+The installed command is:
 
 ```bash
 backstory --help
 ```
 
+## First Run
+
+Initialize Backstory in your repository:
+
 ```bash
 backstory init
+```
+
+This creates a `.backstory/` directory in your repo with the necessary
+storage, indexing, and configuration. It also optionally installs Git hooks
+that help keep session memory linked to your commits.
+
+## Verify
+
+Check that everything is set up correctly:
+
+```bash
+backstory status
+```
+
+If you have an existing commit with a linked session, view its reasoning:
+
+```bash
 backstory why HEAD
 ```
 
@@ -189,7 +230,7 @@ backstory dump --agent claude --transcript ./transcript.md
 | Command | What it does |
 |---|---|
 | `backstory init` | Set up Backstory in the current repo |
-| `backstory dump` | Ingest an AI session into OKF markdown |
+| `backstory dump` | Ingest an AI session into Google's OKF markdown |
 | `backstory attach HEAD` | Link a session to a commit |
 | `backstory why HEAD` | Explain why a commit happened |
 | `backstory show <session>` | View a stored session |
@@ -230,7 +271,6 @@ persists.
 ```text
 .backstory/
   config.json
-  index.sqlite
   knowledge/
     index.md
     sessions/
@@ -241,7 +281,7 @@ persists.
     tombstones.log
 ```
 
-Session memory is stored as OKF-style markdown so it stays human-readable,
+Session memory is stored as Google's OKF-style markdown so it stays human-readable,
 Git-friendly, and agent-friendly.
 
 ## Privacy
@@ -264,8 +304,12 @@ The preferred path is a tool-specific hook, callback, or transcript exporter
 that hands the session to Backstory automatically. `dump` exists as the
 ingestion step, not the primary workflow.
 
+See the [integration guide](docs/integration.md) for step-by-step setup with
+each tool.
+
 ## Documentation
 
+- [Integration guide](docs/integration.md) — Set up Backstory with Claude Code, Codex, Cursor, etc.
 - [Engineering walkthrough](docs/engineering-walkthrough.md)
 - [Product spec](docs/prd.md)
 - [Retrieval model](docs/retrieval.md)

{backstory_cli-0.2.0 → backstory_cli-0.3.0}/README.md

@@ -1,7 +1,7 @@
 # Backstory
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
-[![OKF](https://img.shields.io/badge/knowledge%20format-OKF-orange)](https://cloud.google.com/blog/products/data-analytics)
+[![Google's OKF](https://img.shields.io/badge/knowledge%20format-OKF-orange)](https://cloud.google.com/blog/products/data-analytics)
 
 **Git shows what changed. Backstory shows why.**
 
@@ -18,14 +18,15 @@ markdown, and links it to Git commits so you can retrieve the *why* later.
 
 - Local-first by default — everything stays in your repo
 - Recovers *why* a decision was made, after the codebase has moved on
-- Stores durable session memory as OKF markdown — human-readable,
+- Stores durable session memory as Google's OKF markdown — human-readable,
   Git-friendly, and agent-friendly
 - Links memory to Git commits so the reasoning stays searchable
 - Detects contradictions when later changes reverse earlier decisions
 - Extracts decisions, risks, and follow-ups — not raw chat logs
 
 Backstory is not an AI coding agent. It is the memory layer around
-AI-assisted coding.
+AI-assisted coding — useful whether you're building alone or shipping
+across enterprise teams.
 
 ## Example
 
@@ -148,22 +149,62 @@ The capture and retrieval pipeline has four steps:
 
 Git stays the linkage layer. Backstory stores the reasoning.
 
-## Quick Start
+## Prerequisites
 
-Install the PyPI package:
+- **Python 3.11+** — Backstory requires Python 3.11 or newer.
+- **pip or pipx** — Either package manager works. On fresh machines, `pipx` is
+  recommended because it installs Backstory in its own isolated environment
+  without needing a separate virtual environment.
+- **Git** — Backstory stores session memory inside a Git repository and links
+  it to commits.
+
+## Install
+
+Install directly from the repository:
+
+```bash
+# Using pip (system-wide or in a virtual environment)
+python3 -m pip install git+https://github.com/arpitkath/backstory.git
+
+# Using pipx (isolated, recommended for fresh machines)
+pipx install git+https://github.com/arpitkath/backstory.git
+```
+
+Or install the PyPI package:
 
 ```bash
 python -m pip install backstory-cli
 ```
 
-The installed command is still:
+The installed command is:
 
 ```bash
 backstory --help
 ```
 
+## First Run
+
+Initialize Backstory in your repository:
+
 ```bash
 backstory init
+```
+
+This creates a `.backstory/` directory in your repo with the necessary
+storage, indexing, and configuration. It also optionally installs Git hooks
+that help keep session memory linked to your commits.
+
+## Verify
+
+Check that everything is set up correctly:
+
+```bash
+backstory status
+```
+
+If you have an existing commit with a linked session, view its reasoning:
+
+```bash
 backstory why HEAD
 ```
 
@@ -182,7 +223,7 @@ backstory dump --agent claude --transcript ./transcript.md
 | Command | What it does |
 |---|---|
 | `backstory init` | Set up Backstory in the current repo |
-| `backstory dump` | Ingest an AI session into OKF markdown |
+| `backstory dump` | Ingest an AI session into Google's OKF markdown |
 | `backstory attach HEAD` | Link a session to a commit |
 | `backstory why HEAD` | Explain why a commit happened |
 | `backstory show <session>` | View a stored session |
@@ -223,7 +264,6 @@ persists.
 ```text
 .backstory/
   config.json
-  index.sqlite
   knowledge/
     index.md
     sessions/
@@ -234,7 +274,7 @@ persists.
     tombstones.log
 ```
 
-Session memory is stored as OKF-style markdown so it stays human-readable,
+Session memory is stored as Google's OKF-style markdown so it stays human-readable,
 Git-friendly, and agent-friendly.
 
 ## Privacy
@@ -257,8 +297,12 @@ The preferred path is a tool-specific hook, callback, or transcript exporter
 that hands the session to Backstory automatically. `dump` exists as the
 ingestion step, not the primary workflow.
 
+See the [integration guide](docs/integration.md) for step-by-step setup with
+each tool.
+
 ## Documentation
 
+- [Integration guide](docs/integration.md) — Set up Backstory with Claude Code, Codex, Cursor, etc.
 - [Engineering walkthrough](docs/engineering-walkthrough.md)
 - [Product spec](docs/prd.md)
 - [Retrieval model](docs/retrieval.md)

{backstory_cli-0.2.0 → backstory_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "backstory-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Every AI-assisted commit has a backstory. Never lose it again."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

{backstory_cli-0.2.0 → backstory_cli-0.3.0}/src/backstory/config.py

@@ -4,7 +4,6 @@ import json
 from pathlib import Path
 
 from backstory.storage import (
-    INDEX_DB_NAME,
     KNOWLEDGE_DIR_NAME,
     PENDING_SESSION_NAME,
     REDACTIONS_DIR_NAME,
@@ -15,18 +14,12 @@ from backstory.storage import (
 
 
 DEFAULT_CONFIG = {
-    "version": 1,
     "storage": {
         "root": STORAGE_DIR_NAME,
         "knowledge_dir": KNOWLEDGE_DIR_NAME,
         "sessions_dir": SESSIONS_DIR_NAME,
         "pending_file": PENDING_SESSION_NAME,
         "redactions_dir": REDACTIONS_DIR_NAME,
-        "index_db": INDEX_DB_NAME,
-    },
-    "capture": {
-        "store_git_diff": True,
-        "store_transcripts": True,
     },
     "redaction": {
         "enabled": True,

{backstory_cli-0.2.0 → backstory_cli-0.3.0}/src/backstory/storage.py

@@ -9,7 +9,6 @@ KNOWLEDGE_DIR_NAME = "knowledge"
 SESSIONS_DIR_NAME = "sessions"
 PENDING_SESSION_NAME = "latest.md"
 REDACTIONS_DIR_NAME = "redactions"
-INDEX_DB_NAME = "index.sqlite"
 KNOWLEDGE_INDEX_NAME = "index.md"
 SESSIONS_INDEX_NAME = "index.md"
 
@@ -21,7 +20,6 @@ class BackstoryPaths:
     sessions: Path
     pending: Path
     redactions: Path
-    index_db: Path
     knowledge_index: Path
     sessions_index: Path
 
@@ -36,7 +34,6 @@ def build_storage_paths(repo_root: Path) -> BackstoryPaths:
         sessions=sessions_root,
         pending=sessions_root / PENDING_SESSION_NAME,
         redactions=storage_root / REDACTIONS_DIR_NAME,
-        index_db=storage_root / INDEX_DB_NAME,
         knowledge_index=knowledge_root / KNOWLEDGE_INDEX_NAME,
         sessions_index=sessions_root / SESSIONS_INDEX_NAME,
     )

{backstory_cli-0.2.0 → backstory_cli-0.3.0}/src/backstory_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backstory-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Every AI-assisted commit has a backstory. Never lose it again.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
 # Backstory
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
-[![OKF](https://img.shields.io/badge/knowledge%20format-OKF-orange)](https://cloud.google.com/blog/products/data-analytics)
+[![Google's OKF](https://img.shields.io/badge/knowledge%20format-OKF-orange)](https://cloud.google.com/blog/products/data-analytics)
 
 **Git shows what changed. Backstory shows why.**
 
@@ -25,14 +25,15 @@ markdown, and links it to Git commits so you can retrieve the *why* later.
 
 - Local-first by default — everything stays in your repo
 - Recovers *why* a decision was made, after the codebase has moved on
-- Stores durable session memory as OKF markdown — human-readable,
+- Stores durable session memory as Google's OKF markdown — human-readable,
   Git-friendly, and agent-friendly
 - Links memory to Git commits so the reasoning stays searchable
 - Detects contradictions when later changes reverse earlier decisions
 - Extracts decisions, risks, and follow-ups — not raw chat logs
 
 Backstory is not an AI coding agent. It is the memory layer around
-AI-assisted coding.
+AI-assisted coding — useful whether you're building alone or shipping
+across enterprise teams.
 
 ## Example
 
@@ -155,22 +156,62 @@ The capture and retrieval pipeline has four steps:
 
 Git stays the linkage layer. Backstory stores the reasoning.
 
-## Quick Start
+## Prerequisites
 
-Install the PyPI package:
+- **Python 3.11+** — Backstory requires Python 3.11 or newer.
+- **pip or pipx** — Either package manager works. On fresh machines, `pipx` is
+  recommended because it installs Backstory in its own isolated environment
+  without needing a separate virtual environment.
+- **Git** — Backstory stores session memory inside a Git repository and links
+  it to commits.
+
+## Install
+
+Install directly from the repository:
+
+```bash
+# Using pip (system-wide or in a virtual environment)
+python3 -m pip install git+https://github.com/arpitkath/backstory.git
+
+# Using pipx (isolated, recommended for fresh machines)
+pipx install git+https://github.com/arpitkath/backstory.git
+```
+
+Or install the PyPI package:
 
 ```bash
 python -m pip install backstory-cli
 ```
 
-The installed command is still:
+The installed command is:
 
 ```bash
 backstory --help
 ```
 
+## First Run
+
+Initialize Backstory in your repository:
+
 ```bash
 backstory init
+```
+
+This creates a `.backstory/` directory in your repo with the necessary
+storage, indexing, and configuration. It also optionally installs Git hooks
+that help keep session memory linked to your commits.
+
+## Verify
+
+Check that everything is set up correctly:
+
+```bash
+backstory status
+```
+
+If you have an existing commit with a linked session, view its reasoning:
+
+```bash
 backstory why HEAD
 ```
 
@@ -189,7 +230,7 @@ backstory dump --agent claude --transcript ./transcript.md
 | Command | What it does |
 |---|---|
 | `backstory init` | Set up Backstory in the current repo |
-| `backstory dump` | Ingest an AI session into OKF markdown |
+| `backstory dump` | Ingest an AI session into Google's OKF markdown |
 | `backstory attach HEAD` | Link a session to a commit |
 | `backstory why HEAD` | Explain why a commit happened |
 | `backstory show <session>` | View a stored session |
@@ -230,7 +271,6 @@ persists.
 ```text
 .backstory/
   config.json
-  index.sqlite
   knowledge/
     index.md
     sessions/
@@ -241,7 +281,7 @@ persists.
     tombstones.log
 ```
 
-Session memory is stored as OKF-style markdown so it stays human-readable,
+Session memory is stored as Google's OKF-style markdown so it stays human-readable,
 Git-friendly, and agent-friendly.
 
 ## Privacy
@@ -264,8 +304,12 @@ The preferred path is a tool-specific hook, callback, or transcript exporter
 that hands the session to Backstory automatically. `dump` exists as the
 ingestion step, not the primary workflow.
 
+See the [integration guide](docs/integration.md) for step-by-step setup with
+each tool.
+
 ## Documentation
 
+- [Integration guide](docs/integration.md) — Set up Backstory with Claude Code, Codex, Cursor, etc.
 - [Engineering walkthrough](docs/engineering-walkthrough.md)
 - [Product spec](docs/prd.md)
 - [Retrieval model](docs/retrieval.md)

{backstory_cli-0.2.0 → backstory_cli-0.3.0}/tests/test_config.py

@@ -11,18 +11,12 @@ class ConfigTestCase(unittest.TestCase):
         self.assertEqual(
             DEFAULT_CONFIG,
             {
-                "version": 1,
                 "storage": {
                     "root": ".backstory",
                     "knowledge_dir": "knowledge",
                     "sessions_dir": "sessions",
                     "pending_file": "latest.md",
                     "redactions_dir": "redactions",
-                    "index_db": "index.sqlite",
-                },
-                "capture": {
-                    "store_git_diff": True,
-                    "store_transcripts": True,
                 },
                 "redaction": {
                     "enabled": True,

{backstory_cli-0.2.0 → backstory_cli-0.3.0}/tests/test_storage.py

@@ -19,7 +19,6 @@ class StorageTestCase(unittest.TestCase):
                 sessions=repo_root / ".backstory" / "knowledge" / "sessions",
                 pending=repo_root / ".backstory" / "knowledge" / "sessions" / "latest.md",
                 redactions=repo_root / ".backstory" / "redactions",
-                index_db=repo_root / ".backstory" / "index.sqlite",
                 knowledge_index=repo_root / ".backstory" / "knowledge" / "index.md",
                 sessions_index=repo_root / ".backstory" / "knowledge" / "sessions" / "index.md",
             ),
@@ -35,8 +34,6 @@ class StorageTestCase(unittest.TestCase):
             self.assertTrue(paths.knowledge.is_dir())
             self.assertTrue(paths.sessions.is_dir())
             self.assertTrue(paths.redactions.is_dir())
-            self.assertEqual(paths.index_db, repo_root / ".backstory" / "index.sqlite")
-            self.assertFalse(paths.index_db.exists())
 
 
 class GitHelpersTestCase(unittest.TestCase):