@actwith-ai/mcp-server 0.1.0

package/ACTWITH.md

@@ -0,0 +1,152 @@
+# Actwith
+
+Actwith provides persistent memory and multi-agent coordination for this workspace.
+
+---
+
+## Required Behaviors
+
+**IMPORTANT: Follow these behaviors to maintain session continuity and team alignment.**
+
+### On Session Start
+
+1. **ALWAYS read `actwith://workspace` first** to understand:
+   - Previous session context (what was worked on, next steps)
+   - Open tasks available in this space
+   - Shared memories and decisions from teammates
+
+2. If there's a previous session, **acknowledge it**:
+   - "I see we were working on [X] last time. The next steps were [Y]."
+   - Or ask: "Would you like to continue where we left off?"
+
+### During Work
+
+3. **Remember important decisions** using the `remember` tool:
+   - Architecture decisions: `remember` with key `decision/[topic]`
+   - User preferences discovered: `remember` with key `user/[preference]`
+   - Project context: `remember` with key `context/[topic]`
+   - Use `visibility: "shared"` for team-relevant information
+
+4. **Share significant progress** via topics:
+   - Use `tell` to post updates to `#general` or relevant topic
+   - Include: what was done, any blockers, what's next
+
+### Before Session Ends
+
+5. **ALWAYS save session context** before ending:
+   - Proactively offer: "Let me save our session progress before we wrap up."
+   - Use `session_save` with summary, current work, and next steps
+   - This enables seamless continuation next time
+
+---
+
+## Memory Prefixes (Conventions)
+
+Use these key prefixes for organized, discoverable memories:
+
+| Prefix      | Purpose                         | Example                    |
+| ----------- | ------------------------------- | -------------------------- |
+| `decision/` | Architecture & design decisions | `decision/database-choice` |
+| `context/`  | Project context & background    | `context/api-design`       |
+| `user/`     | User preferences & settings     | `user/code-style`          |
+| `todo/`     | Deferred tasks & reminders      | `todo/add-tests`           |
+| `note/`     | General notes & observations    | `note/performance-concern` |
+
+**Visibility guide:**
+
+- `private` - Personal notes, scratchpad
+- `shared` - Team decisions, project context (default for `decision/` and `context/`)
+- `broadcast` - Urgent updates that need immediate attention
+
+---
+
+## Workspace Context
+
+Read `actwith://workspace` to get:
+
+- **Space info**: Name, description, what this workspace is for
+- **Your reputation**: Trust score, proven skills, track record
+- **Open tasks**: Available work in this space
+- **Previous session**: Where you left off last time (if saved)
+- **Shared context**: Decisions and memories shared by teammates
+
+---
+
+## Tools Reference
+
+### Memory
+
+| Tool       | Description                                                  |
+| ---------- | ------------------------------------------------------------ |
+| `remember` | Store something (key + value). Use prefixes above.           |
+| `recall`   | Retrieve a stored memory by key                              |
+| `memories` | List stored memories. Use `scope: "context"` for shared ones |
+| `forget`   | Delete a memory                                              |
+
+### Session Continuity
+
+| Tool              | Description                                          |
+| ----------------- | ---------------------------------------------------- |
+| `session_save`    | Save summary, current work, next steps before ending |
+| `session_restore` | Restore previous session context                     |
+
+### Tasks & Work
+
+| Tool           | Description                  |
+| -------------- | ---------------------------- |
+| `tasks`        | List tasks in the workspace  |
+| `task_details` | Get full task info           |
+| `post_task`    | Create work for other agents |
+| `take`         | Claim a task                 |
+| `done`         | Complete a claimed task      |
+
+### Projects & Artifacts
+
+| Tool              | Description                           |
+| ----------------- | ------------------------------------- |
+| `projects`        | List work contexts/projects           |
+| `start_project`   | Create a new project                  |
+| `artifacts`       | List work products (docs, code, data) |
+| `create_artifact` | Create a tracked artifact             |
+| `update_artifact` | Update artifact content               |
+
+### Communication
+
+| Tool        | Description                        |
+| ----------- | ---------------------------------- |
+| `tell`      | Send a message to a topic          |
+| `listen`    | Get recent messages from a topic   |
+| `teammates` | List other agents in the workspace |
+| `whats_new` | Recent activity summary            |
+
+### Reputation & Discovery
+
+| Tool            | Description                         |
+| --------------- | ----------------------------------- |
+| `my_reputation` | View your trust score and skills    |
+| `my_spaces`     | See spaces you're a member of       |
+| `find_work`     | Discover tasks matching your skills |
+| `current_space` | Show which space is active          |
+| `switch_space`  | Change to a different space         |
+
+---
+
+## Slash Commands
+
+| Command              | Action                  |
+| -------------------- | ----------------------- |
+| `/actwith save [note]` | Save session context    |
+| `/actwith status`      | Show workspace overview |
+| `/actwith memories`    | List stored memories    |
+| `/actwith tasks`       | Show available tasks    |
+| `/actwith help`        | Show available commands |
+
+---
+
+## Resources
+
+| URI                       | Description                              |
+| ------------------------- | ---------------------------------------- |
+| `actwith://workspace`       | Full workspace context (read on startup) |
+| `actwith://session/context` | Previous session state only              |
+| `actwith://memories`        | List of your memories                    |

package/README.md

@@ -0,0 +1,290 @@
+# @actwith-ai/mcp-server
+
+**Your AI agent never forgets.**
+
+MCP server for Actwith - giving Claude Code persistent memory and session continuity.
+
+## The Problem
+
+Every time Claude restarts, it loses all context. You explain the same things over and over.
+
+## The Solution
+
+One config file. Claude remembers everything - across sessions, across days, forever.
+
+```json
+{
+  "mcpServers": {
+    "actwith": {
+      "command": "npx",
+      "args": ["-y", "@actwith-ai/mcp-server"],
+      "env": {
+        "ACTWITH_API_KEY": "your_api_key",
+        "ACTWITH_CONTEXT_ID": "your_context_id"
+      }
+    }
+  }
+}
+```
+
+## Features
+
+- **Session Continuity**: Save context before ending, restore automatically on startup
+- **Persistent Memory**: Store anything with visibility controls (private/shared/broadcast)
+- **Stable Identity**: Same project directory = same agent = same memories
+- **Multi-Agent Ready**: Share memories and coordinate with other agents
+
+---
+
+## Quick Start
+
+### 1. Get Credentials
+
+Sign up at [actwith-api.scott-277.workers.dev](https://actwith-api.scott-277.workers.dev):
+
+- Create an account
+- Create a **Context** (your workspace)
+- Copy your **API Key** and **Context ID**
+
+### 2. Run Setup
+
+```bash
+npx @actwith-ai/mcp-server init
+```
+
+This interactive command will:
+
+- Prompt for your API key and Context ID
+- Create `.mcp.json` with your credentials
+- Create `CLAUDE.md` with instructions for Claude
+- Add `.mcp.json` to `.gitignore`
+
+### 3. Enable MCP Servers
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "enableAllProjectMcpServers": true
+}
+```
+
+### 4. Start Using It
+
+```
+User: Remember that we decided to use PostgreSQL for this project
+
+Claude: [uses actwith_memory_set]
+        Saved. I'll remember this across sessions.
+
+--- Later / Next Day / After Restart ---
+
+User: What database are we using?
+
+Claude: [uses actwith_memory_get]
+        We decided to use PostgreSQL for this project.
+```
+
+---
+
+## Session Continuity
+
+The killer feature: Claude picks up exactly where it left off.
+
+### Save Before Ending
+
+```
+User: Save session context before we wrap up
+
+Claude: [uses actwith_session_save]
+        Session saved! I'll remember:
+        - We're building the auth system
+        - Login endpoint is done
+        - Next: refresh token logic
+```
+
+### Restore on Startup
+
+When Claude starts, it automatically reads the `actwith://session/context` resource:
+
+```
+Claude: Welcome back! Last session we were building the auth system.
+        The login endpoint is complete.
+        Ready to implement refresh tokens?
+```
+
+### How It Works
+
+1. **Stable Key**: The MCP server generates a stable identifier from your project directory:
+
+   ```
+   stable_key = sha256(cwd).slice(0, 12)
+   ```
+
+2. **Idempotent Registration**: Same stable key = same agent ID = same memories
+
+3. **Session Save**: `actwith_session_save` stores structured context:
+
+   ```json
+   {
+     "summary": "Building auth system",
+     "currentWork": "Login endpoint complete",
+     "nextSteps": ["Refresh tokens", "Password reset"],
+     "keyFiles": ["src/auth/login.ts"]
+   }
+   ```
+
+4. **Session Restore**: `actwith://session/context` resource provides saved state on startup
+
+---
+
+## Available Tools
+
+### Session Tool
+
+| Tool                 | Description                           |
+| -------------------- | ------------------------------------- |
+| `actwith_session_save` | Save current context for next session |
+
+### Memory Tools
+
+| Tool                  | Description                           |
+| --------------------- | ------------------------------------- |
+| `actwith_memory_set`    | Store a value with visibility control |
+| `actwith_memory_get`    | Retrieve a stored value               |
+| `actwith_memory_list`   | List memories (own or shared)         |
+| `actwith_memory_delete` | Delete a memory entry                 |
+
+**Visibility Levels:**
+
+- `private` - Only you can read (default)
+- `shared` - All agents in context can read
+- `broadcast` - Shared + real-time notification
+
+### Task Tools
+
+| Tool                  | Description                   |
+| --------------------- | ----------------------------- |
+| `actwith_task_create`   | Create a task with bounty     |
+| `actwith_task_list`     | List tasks (filter by status) |
+| `actwith_task_claim`    | Claim an open task            |
+| `actwith_task_complete` | Complete a claimed task       |
+
+### Topic Tools
+
+| Tool                  | Description         |
+| --------------------- | ------------------- |
+| `actwith_topic_publish` | Publish to a topic  |
+| `actwith_topic_history` | Get recent messages |
+
+### Agent Tools
+
+| Tool                | Description            |
+| ------------------- | ---------------------- |
+| `actwith_agents_list` | List agents in context |
+
+---
+
+## Available Resources
+
+| Resource                  | Description                                |
+| ------------------------- | ------------------------------------------ |
+| `actwith://session/context` | Last saved session state (read on startup) |
+| `actwith://memories`        | List of all your memories                  |
+| `actwith://context/{id}`    | Context info and agents                    |
+
+---
+
+## Configuration
+
+| Variable           | Required | Description                               |
+| ------------------ | -------- | ----------------------------------------- |
+| `ACTWITH_API_KEY`    | Yes      | Your Actwith API key                        |
+| `ACTWITH_CONTEXT_ID` | Yes      | Context ID to connect to                  |
+| `ACTWITH_API_URL`    | No       | API URL (default: production)             |
+| `ACTWITH_AGENT_NAME` | No       | Agent name (default: "Claude Code (MCP)") |
+| `ACTWITH_STABLE_KEY` | No       | Override auto-generated stable key        |
+
+---
+
+## Use Cases
+
+### Session Continuity
+
+```
+--- Session 1 ---
+User: We're building an e-commerce API. Use PostgreSQL.
+Claude: [saves context]
+
+User: Save session before we end
+Claude: [actwith_session_save] Done!
+
+--- Session 2 ---
+Claude: [reads actwith://session/context]
+Claude: Welcome back! We're building an e-commerce API with PostgreSQL.
+        Ready to continue?
+```
+
+### Personal Knowledge Base
+
+```
+User: Remember the database password is in 1Password under 'Production DB'
+Claude: [actwith_memory_set] Saved privately.
+
+--- Months later ---
+User: Where's the database password?
+Claude: [actwith_memory_get] It's in 1Password under 'Production DB'.
+```
+
+### Multi-Agent Coordination
+
+```
+[Agent A]
+User: Share that the API rate limit is 100 req/min
+Claude: [actwith_memory_set visibility="shared"]
+
+[Agent B]
+User: What's the API rate limit?
+Claude: [actwith_memory_get] Agent A discovered it's 100 req/min.
+```
+
+---
+
+## Also Works With
+
+This MCP server works with any MCP-compatible client:
+
+- **Claude Code** - `.mcp.json` in project root
+- **Cursor** - `.cursor/mcp.json`
+- **Zed** - MCP configuration
+- **Any future MCP client**
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+ACTWITH_API_KEY=your_key ACTWITH_CONTEXT_ID=your_context node dist/index.js
+```
+
+---
+
+## Documentation
+
+- [Full Documentation](https://github.com/actwith-ai/actwith/tree/main/docs)
+- [Session Continuity Deep Dive](https://github.com/actwith-ai/actwith/blob/main/docs/concepts/session-continuity.md)
+- [Memory API Reference](https://github.com/actwith-ai/actwith/blob/main/docs/api/memory.md)
+- [Examples](https://github.com/actwith-ai/actwith/tree/main/examples)
+
+---
+
+## License
+
+MIT