Metadata-Version: 2.4
Name: sessionbridge
Version: 0.1.1
Summary: MCP server for persistent cross-repo session memory with smart status tracking
Project-URL: Homepage, https://github.ibm.com/aakshu/sessionbridge
Project-URL: Documentation, https://github.ibm.com/aakshu/sessionbridge#readme
Project-URL: Repository, https://github.ibm.com/aakshu/sessionbridge
Project-URL: Issues, https://github.ibm.com/aakshu/sessionbridge/issues
Author-email: Aakash Raghunathan <aakshu@ibm.com>, Tanmay Sreejith <Tan.may@ibm.com>
License: MIT
License-File: LICENSE
Keywords: ai,assistant,bob,context,mcp,memory,session
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: fastmcp>=0.1.0
Description-Content-Type: text/markdown

# SessionBridge

**MCP server for persistent cross-repo session memory with smart status tracking**

SessionBridge gives AI assistants like Bob persistent memory across conversations, with intelligent status tracking and event-driven progress saving.

## Features

- 🧠 **Persistent Memory** - Sessions survive across conversations and context switches
- 📊 **Smart Status Tracking** - Automatically infers Done/Blocked/Next from your summaries
- 🎯 **Task Goals** - Every session starts with a clear objective
- 🔄 **Multi-Repo Support** - Track work across multiple codebases
- ⚡ **Event-Driven** - Save progress only when it matters
- 🎭 **Optional** - Works alongside normal conversations, not forced

## Quick Start

### Installation with uvx (Recommended)

```bash
# No installation needed! Run directly with uvx
uvx sessionbridge
```

### Bob MCP Configuration

Add to your `~/.bob/mcp.json`:

```json
{
  "mcpServers": {
    "sessionbridge": {
      "command": "uvx",
      "args": ["sessionbridge"],
      "alwaysAllow": [
        "list_sessions",
        "resume_session",
        "new_session",
        "save_progress",
        "end_session",
        "add_repos_to_session"
      ]
    }
  }
}
```

Restart Bob, and SessionBridge is ready!

## Usage

### Creating a Session

```
You: "Create a session called api-fix to fix the 500 errors in the user endpoint"
Bob: Creates session with goal and repo tracking
```

### Working with Sessions

```
You: "I want to refactor the authentication system"
Bob: "Would you like me to:
      1. Create a new session to track this work?
      2. Continue an existing session?
      3. Just help without session tracking?"
```

### Saving Progress

Bob automatically saves progress when:
- ✅ Root cause identified
- ✅ Architectural decision made
- ✅ Task completed
- ✅ Blocking issue hit
- ✅ Switching context

### Resuming Work

```
You: "Resume the api-fix session"
Bob: Loads full context including status, progress, and next steps
```

## Session File Format

Sessions are stored as markdown in `~/.sessionbridge/sessions/`:

```markdown
# api-fix
**Goal:** Fix 500 errors in user endpoint
**Repos:** /code/api-service, /code/database
**Created:** 2026-04-08

**Status:** in-progress
- Done: Identified root cause in query.py, Fixed N+1 problem
- Blocked on: Database migration approval
- Next: Deploy to staging, Run integration tests

## 2026-04-08
Identified root cause in database query. Fixed N+1 problem in user endpoint.
Blocked on database migration approval from DBA team.

**[Session ended at 18:30]**
Completed fix and local testing. Ready for staging deployment.
```

## MCP Tools

### 1. new_session
Create a new session with task goal and repositories.

**When to use:** User explicitly wants session tracking for substantial work.

### 2. resume_session
Load session context. Optionally add new repositories.

**When to use:** Continuing previous work or expanding to new repos.

### 3. save_progress
Save significant progress with smart status inference.

**When to use:** Key findings, decisions, completions, blockers, or context switches.

### 4. end_session
End session with wrap-up summary.

**When to use:** Task complete, switching tasks, or handing off work.

### 5. list_sessions
List all sessions with last-modified dates.

**When to use:** Checking available sessions or helping user choose.

### 6. add_repos_to_session
Add repositories to existing session.

**When to use:** Work expands to additional codebases.

## Smart Status Tracking

SessionBridge automatically extracts status from your summaries:

```
Summary: "Completed JWT validation. Blocked on API key - waiting for DevOps. 
          Next: integrate with API service."

Inferred Status:
- Status: blocked
- Done: JWT validation
- Blocked on: API key - waiting for DevOps
- Next: integrate with API service
```

### Keywords

- **Done**: completed, finished, implemented, fixed, resolved, deployed
- **Blocked**: blocked on, waiting for, need, requires, pending
- **Next**: next, todo, need to, should, will, plan to

## Advanced Features

### Dynamic Repo Management

```python
# Add repos when resuming
resume_session(name="api-fix", add_repos=["/code/frontend", "/code/mobile"])

# Or add explicitly
add_repos_to_session(name="api-fix", repos=["/code/admin"])
```

### Auto-Trimming

Sessions automatically trim to last 20 date entries when token count exceeds 3000, keeping context manageable.

## Installation (Development)

```bash
# Clone repository
git clone https://github.com/yourusername/sessionbridge
cd sessionbridge

# Install in development mode
pip install -e .

# Run directly
sessionbridge
```

## Requirements

- Python 3.8+
- fastmcp

## Why SessionBridge?

**Problem:** AI assistants lose context between conversations. You have to re-explain your project, what you've done, and what's next.

**Solution:** SessionBridge gives your AI assistant persistent memory with:
- Clear task goals
- Automatic status tracking
- Progress history
- Multi-repo awareness
- Event-driven saving (not noisy)

**Result:** Pick up exactly where you left off, even days later.

## Best Practices

### 1. Use Sessions for Substantial Work
- ✅ Multi-day projects
- ✅ Cross-repo refactoring
- ✅ Complex bug investigations
- ❌ Quick questions
- ❌ One-off tasks

### 2. Write Meaningful Summaries
```
❌ Bad: "Made some changes"
✅ Good: "Implemented JWT refresh token logic in auth.py. Tested with 1000 concurrent users."
```

### 3. Let Sessions Be Optional
SessionBridge works alongside normal conversations. Use sessions when they add value, skip them when they don't.

## Contributing

Contributions welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## Authors

- Aakash Raghunathan (aakshu@ibm.com)
- Tanmay Sreejith (Tan.may@ibm.com)

## Links

- [GitHub Repository](https://github.com/yourusername/sessionbridge)
- [Issue Tracker](https://github.com/yourusername/sessionbridge/issues)
- [PyPI Package](https://pypi.org/project/sessionbridge/)

---

**Made with ❤️ for better AI assistant workflows**