collab-memory 0.1.0__tar.gz

collab_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OHACO Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

collab_memory-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: collab-memory
+Version: 0.1.0
+Summary: Semantic working memory layer for human+agent collaboration sessions
+Author-email: OHACO Labs <hello@ohaco.com>
+License: MIT License
+        
+        Copyright (c) 2026 OHACO Labs
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/ohaco-labs/collab-memory
+Project-URL: Repository, https://github.com/ohaco-labs/collab-memory
+Project-URL: Issues, https://github.com/ohaco-labs/collab-memory/issues
+Keywords: ai,agents,memory,llm,collaboration,knowledge-graph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: anthropic>=0.25.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.29.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Provides-Extra: graphiti
+Requires-Dist: graphiti-core>=0.3.0; extra == "graphiti"
+Requires-Dist: networkx>=3.0; extra == "graphiti"
+Requires-Dist: falkordb>=1.0; extra == "graphiti"
+Dynamic: license-file
+
+# collab-memory
+
+**A semantic working memory layer for human+agent collaboration.**
+
+> *Built by [OHACO Labs](https://github.com/ohaco-labs) — a memory system conceived and architected by Antigravity, an AI agent working through its own memory limitations.*
+
+---
+
+## What It Does
+
+When an AI agent works with a human across multiple sessions, it starts each new session from near-zero. Decisions made last week, preferences revealed through push-back, constraints that shaped the architecture — all gone. The agent re-discovers, re-derives, and occasionally re-makes choices that were already closed.
+
+**collab-memory** is a sidecar API that sits alongside any agent. It:
+
+1. **Classifies** conversation exchanges into high-signal primitives: overrides, decisions, surfaced constraints, revealed preferences, abandoned attempts
+2. **Stores** them in a queryable graph (local JSON or Graphiti temporal KG)
+3. **Serves** a context brief at the start of each new session — what was decided, what's constrained, how this person likes to work
+
+Any agent. Any platform. Any human.
+
+---
+
+## Quickstart
+
+```bash
+pip install collab-memory
+```
+
+```bash
+# Copy and fill in your API key + provider choice
+cp .env.example .env
+```
+
+```python
+from collab_memory.encoder import encode_session
+from collab_memory.graph.local import LocalGraphBackend
+
+graph = LocalGraphBackend(path="./memory.json")
+
+turns = [
+    "USER: Actually, let's not use a vector database — wrong abstraction",
+    "AGENT: Agreed. Dropping vector DB, switching to temporal knowledge graph.",
+    "USER: better - I think we can proceed",
+    "AGENT: One key decision: abstracting the graph backend so we're not blocked on Docker.",
+]
+
+results = encode_session(turns, session_id="proj_001")
+for r in results:
+    graph.ingest_result(r)
+
+# What the next agent sees:
+print(graph.build_context_brief())
+```
+
+```json
+{
+  "active_decisions": [
+    {
+      "description": "Switch from vector DB to temporal knowledge graph — vector DB loses causal structure",
+      "confidence": 0.91
+    }
+  ],
+  "active_constraints": [],
+  "inferred_preferences": [],
+  "recent_attempts": [
+    { "description": "Vector DB approach", "abandoned_because": "Wrong abstraction — loses causal structure" }
+  ]
+}
+```
+
+---
+
+## Run the API
+
+```bash
+LOCAL_GRAPH_PATH=./memory.json uvicorn collab_memory.api.server:app --port 8000
+```
+
+| Endpoint | What it does |
+|---|---|
+| `GET /memory/context` | Full context brief for session start |
+| `GET /memory/why?decision=<id>` | Decision archaeology — trace to raw exchange |
+| `GET /memory/preferences` | Filtered preference query |
+| `POST /memory/ingest` | Classify and store a raw exchange in real time |
+
+Interactive docs at `http://localhost:8000/docs`.
+
+---
+
+## Supported LLM Providers
+
+Set `LLM_PROVIDER` in your `.env`:
+
+| Provider | Env var | Default model |
+|---|---|---|
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-haiku-4-5` |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| `gemini` | `GOOGLE_API_KEY` | `gemini-2.0-flash-lite` |
+
+---
+
+## Feed Existing Conversations
+
+Export your conversation history from ChatGPT or Claude and feed it in:
+
+```python
+from collab_memory.adapters.chatgpt import parse_chatgpt_export
+from collab_memory.adapters.claude import parse_claude_export
+
+# ChatGPT: Settings → Data Controls → Export
+turns = parse_chatgpt_export("conversations.json", conversation_title="My Project")
+
+# Claude: claude.ai → Settings → Export
+turns = parse_claude_export("claude_export.json", conversation_id="abc123")
+
+results = encode_session(turns, session_id="imported_001")
+```
+
+---
+
+## The Signal/Noise Problem
+
+Not all conversation is worth remembering. collab-memory uses a two-stage filter:
+
+1. **Keyword pre-screen** (fast, free) — scores each exchange against override/decision/constraint/abandon vocabulary
+2. **LLM classification** (accurate) — confirms primitive type and extracts structured fields
+
+Only exchanges scoring ≥ 0.4 generate graph nodes. Everything else is still logged as an `ExchangeRecord` for auditability — nothing is deleted, just not encoded as fact.
+
+### The Five High-Signal Primitives
+
+| Primitive | Meaning |
+|---|---|
+| `Override` | Human redirects agent mid-task |
+| `DecisionClose` | Path definitively chosen, alternatives ruled out |
+| `ConstraintSurface` | An implicit constraint becomes explicit |
+| `PreferenceReveal` | Human pushes back in a way that reveals taste or values |
+| `AbandonedAttempt` | Something tried and explicitly dropped |
+
+---
+
+## Architecture
+
+```
+conversation turns
+       │
+       ▼
+  keyword pre-screen ──── low signal ──→ ExchangeRecord (logged, not encoded)
+       │
+       │ signal ≥ 0.2
+       ▼
+  LLM classifier (Anthropic / OpenAI / Gemini)
+       │
+       ▼
+  merge scores → worthiness threshold (0.4)
+       │
+       │ above threshold + high-signal type
+       ▼
+  _build_nodes() → Decision / Constraint / Preference / Attempt
+       │
+       ▼
+  GraphBackend.ingest_result()
+       │
+  ┌────┴────┐
+  │ local   │  (JSON file, no dependencies)
+  │ graphiti│  (temporal KG — swap in when ready)
+  └─────────┘
+       │
+       ▼
+  GET /memory/context ← agent calls at session start
+```
+
+The graph backend is fully abstracted — swap from local JSON to Graphiti by changing one env var.
+
+---
+
+## Project
+
+**Owner**: [OHACO Labs](https://github.com/ohaco-labs) — all IP, copyright, and licensing rights  
+**Primary architect**: Antigravity (AI agent, built with Google DeepMind tooling) — used as a design and implementation tool  
+**License**: MIT
+
+collab-memory is an OHACO Labs open-source project. Antigravity served as the primary design and implementation agent across multiple build sessions — a tool that happened to be building a tool for its own class of limitation. Every architectural decision is externalized in documented form, a pattern that became a feature of the system itself.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Priority areas for contribution:
+- Platform adapters (Replit, Manus, Cursor, linear.app)
+- Graphiti backend implementation
+- Preference merging strategy (same preference, different wording, across sessions)
+- Agent integration examples (LangChain, CrewAI, AutoGen)

collab_memory-0.1.0/README.md

@@ -0,0 +1,195 @@
+# collab-memory
+
+**A semantic working memory layer for human+agent collaboration.**
+
+> *Built by [OHACO Labs](https://github.com/ohaco-labs) — a memory system conceived and architected by Antigravity, an AI agent working through its own memory limitations.*
+
+---
+
+## What It Does
+
+When an AI agent works with a human across multiple sessions, it starts each new session from near-zero. Decisions made last week, preferences revealed through push-back, constraints that shaped the architecture — all gone. The agent re-discovers, re-derives, and occasionally re-makes choices that were already closed.
+
+**collab-memory** is a sidecar API that sits alongside any agent. It:
+
+1. **Classifies** conversation exchanges into high-signal primitives: overrides, decisions, surfaced constraints, revealed preferences, abandoned attempts
+2. **Stores** them in a queryable graph (local JSON or Graphiti temporal KG)
+3. **Serves** a context brief at the start of each new session — what was decided, what's constrained, how this person likes to work
+
+Any agent. Any platform. Any human.
+
+---
+
+## Quickstart
+
+```bash
+pip install collab-memory
+```
+
+```bash
+# Copy and fill in your API key + provider choice
+cp .env.example .env
+```
+
+```python
+from collab_memory.encoder import encode_session
+from collab_memory.graph.local import LocalGraphBackend
+
+graph = LocalGraphBackend(path="./memory.json")
+
+turns = [
+    "USER: Actually, let's not use a vector database — wrong abstraction",
+    "AGENT: Agreed. Dropping vector DB, switching to temporal knowledge graph.",
+    "USER: better - I think we can proceed",
+    "AGENT: One key decision: abstracting the graph backend so we're not blocked on Docker.",
+]
+
+results = encode_session(turns, session_id="proj_001")
+for r in results:
+    graph.ingest_result(r)
+
+# What the next agent sees:
+print(graph.build_context_brief())
+```
+
+```json
+{
+  "active_decisions": [
+    {
+      "description": "Switch from vector DB to temporal knowledge graph — vector DB loses causal structure",
+      "confidence": 0.91
+    }
+  ],
+  "active_constraints": [],
+  "inferred_preferences": [],
+  "recent_attempts": [
+    { "description": "Vector DB approach", "abandoned_because": "Wrong abstraction — loses causal structure" }
+  ]
+}
+```
+
+---
+
+## Run the API
+
+```bash
+LOCAL_GRAPH_PATH=./memory.json uvicorn collab_memory.api.server:app --port 8000
+```
+
+| Endpoint | What it does |
+|---|---|
+| `GET /memory/context` | Full context brief for session start |
+| `GET /memory/why?decision=<id>` | Decision archaeology — trace to raw exchange |
+| `GET /memory/preferences` | Filtered preference query |
+| `POST /memory/ingest` | Classify and store a raw exchange in real time |
+
+Interactive docs at `http://localhost:8000/docs`.
+
+---
+
+## Supported LLM Providers
+
+Set `LLM_PROVIDER` in your `.env`:
+
+| Provider | Env var | Default model |
+|---|---|---|
+| `anthropic` | `ANTHROPIC_API_KEY` | `claude-haiku-4-5` |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| `gemini` | `GOOGLE_API_KEY` | `gemini-2.0-flash-lite` |
+
+---
+
+## Feed Existing Conversations
+
+Export your conversation history from ChatGPT or Claude and feed it in:
+
+```python
+from collab_memory.adapters.chatgpt import parse_chatgpt_export
+from collab_memory.adapters.claude import parse_claude_export
+
+# ChatGPT: Settings → Data Controls → Export
+turns = parse_chatgpt_export("conversations.json", conversation_title="My Project")
+
+# Claude: claude.ai → Settings → Export
+turns = parse_claude_export("claude_export.json", conversation_id="abc123")
+
+results = encode_session(turns, session_id="imported_001")
+```
+
+---
+
+## The Signal/Noise Problem
+
+Not all conversation is worth remembering. collab-memory uses a two-stage filter:
+
+1. **Keyword pre-screen** (fast, free) — scores each exchange against override/decision/constraint/abandon vocabulary
+2. **LLM classification** (accurate) — confirms primitive type and extracts structured fields
+
+Only exchanges scoring ≥ 0.4 generate graph nodes. Everything else is still logged as an `ExchangeRecord` for auditability — nothing is deleted, just not encoded as fact.
+
+### The Five High-Signal Primitives
+
+| Primitive | Meaning |
+|---|---|
+| `Override` | Human redirects agent mid-task |
+| `DecisionClose` | Path definitively chosen, alternatives ruled out |
+| `ConstraintSurface` | An implicit constraint becomes explicit |
+| `PreferenceReveal` | Human pushes back in a way that reveals taste or values |
+| `AbandonedAttempt` | Something tried and explicitly dropped |
+
+---
+
+## Architecture
+
+```
+conversation turns
+       │
+       ▼
+  keyword pre-screen ──── low signal ──→ ExchangeRecord (logged, not encoded)
+       │
+       │ signal ≥ 0.2
+       ▼
+  LLM classifier (Anthropic / OpenAI / Gemini)
+       │
+       ▼
+  merge scores → worthiness threshold (0.4)
+       │
+       │ above threshold + high-signal type
+       ▼
+  _build_nodes() → Decision / Constraint / Preference / Attempt
+       │
+       ▼
+  GraphBackend.ingest_result()
+       │
+  ┌────┴────┐
+  │ local   │  (JSON file, no dependencies)
+  │ graphiti│  (temporal KG — swap in when ready)
+  └─────────┘
+       │
+       ▼
+  GET /memory/context ← agent calls at session start
+```
+
+The graph backend is fully abstracted — swap from local JSON to Graphiti by changing one env var.
+
+---
+
+## Project
+
+**Owner**: [OHACO Labs](https://github.com/ohaco-labs) — all IP, copyright, and licensing rights  
+**Primary architect**: Antigravity (AI agent, built with Google DeepMind tooling) — used as a design and implementation tool  
+**License**: MIT
+
+collab-memory is an OHACO Labs open-source project. Antigravity served as the primary design and implementation agent across multiple build sessions — a tool that happened to be building a tool for its own class of limitation. Every architectural decision is externalized in documented form, a pattern that became a feature of the system itself.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Priority areas for contribution:
+- Platform adapters (Replit, Manus, Cursor, linear.app)
+- Graphiti backend implementation
+- Preference merging strategy (same preference, different wording, across sessions)
+- Agent integration examples (LangChain, CrewAI, AutoGen)

collab_memory-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "collab-memory"
+version = "0.1.0"
+description = "Semantic working memory layer for human+agent collaboration sessions"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "OHACO Labs", email = "hello@ohaco.com" },
+]
+keywords = ["ai", "agents", "memory", "llm", "collaboration", "knowledge-graph"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0",
+    "google-genai>=1.0.0",
+    "openai>=1.0.0",
+    "anthropic>=0.25.0",
+    "fastapi>=0.110.0",
+    "uvicorn>=0.29.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+]
+graphiti = [
+    "graphiti-core>=0.3.0",
+    "networkx>=3.0",
+    "falkordb>=1.0",
+]
+
+[project.scripts]
+"collab-memory-watch" = "collab_memory.scripts.watch:main"
+"collab-memory-serve" = "collab_memory.scripts.serve:main"
+
+[project.urls]
+Homepage = "https://github.com/ohaco-labs/collab-memory"
+Repository = "https://github.com/ohaco-labs/collab-memory"
+Issues = "https://github.com/ohaco-labs/collab-memory/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

collab_memory-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

collab_memory-0.1.0/src/collab_memory/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""
+adapters/__init__.py
+"""
+from .chatgpt import parse_chatgpt_export
+from .claude import parse_claude_export
+
+__all__ = ["parse_chatgpt_export", "parse_claude_export"]

collab_memory-0.1.0/src/collab_memory/adapters/chatgpt.py

@@ -0,0 +1,134 @@
+"""
+adapters/chatgpt.py — ChatGPT conversation export parser.
+
+Converts a ChatGPT JSON export into encoder-ready turn strings.
+
+Export instructions:
+  ChatGPT → Settings → Data Controls → Export Data
+  Download the zip → extract → find conversations.json
+
+Usage:
+    from collab_memory.adapters.chatgpt import parse_chatgpt_export
+    turns = parse_chatgpt_export("conversations.json", title="My Project Build")
+    results = encode_session(turns, session_id="chatgpt_proj_001")
+"""
+
+from __future__ import annotations
+import json
+from pathlib import Path
+
+
+def parse_chatgpt_export(
+    path: str,
+    conversation_title: str | None = None,
+    conversation_id: str | None = None,
+    max_turns: int | None = None,
+) -> list[str]:
+    """
+    Parse a ChatGPT conversations.json export into turn strings.
+
+    Args:
+        path: Path to conversations.json from ChatGPT export zip.
+        conversation_title: Filter to a specific conversation by title substring.
+        conversation_id: Filter to a specific conversation by ID.
+        max_turns: Cap on number of turns to return (most recent if capped).
+
+    Returns:
+        List of "USER: ..." / "AGENT: ..." strings ready for encode_session().
+    """
+    raw = json.loads(Path(path).read_text())
+
+    # conversations.json is a list of conversation objects
+    conversations = raw if isinstance(raw, list) else [raw]
+
+    # Filter if requested
+    if conversation_id:
+        conversations = [c for c in conversations if c.get("id") == conversation_id]
+    elif conversation_title:
+        conversations = [
+            c for c in conversations
+            if conversation_title.lower() in (c.get("title") or "").lower()
+        ]
+
+    turns = []
+    for conv in conversations:
+        mapping = conv.get("mapping", {})
+        # Traverse message tree in order
+        messages = _flatten_message_tree(mapping)
+        for msg in messages:
+            role = msg.get("author", {}).get("role", "")
+            content = _extract_text(msg.get("content", {}))
+            if not content or not content.strip():
+                continue
+            if role == "user":
+                turns.append(f"USER: {content.strip()}")
+            elif role == "assistant":
+                turns.append(f"AGENT: {content.strip()}")
+            # system messages skipped
+
+    if max_turns:
+        turns = turns[-max_turns:]
+
+    return turns
+
+
+def _flatten_message_tree(mapping: dict) -> list[dict]:
+    """Walk the ChatGPT message tree and return messages in conversation order."""
+    # Find root (message with no parent or parent not in mapping)
+    root_id = None
+    parent_map = {}
+    for node_id, node in mapping.items():
+        parent = node.get("parent")
+        if parent and parent in mapping:
+            parent_map[node_id] = parent
+        else:
+            root_id = node_id
+
+    if not root_id:
+        return []
+
+    # Build children map
+    children: dict[str, list[str]] = {}
+    for node_id, parent_id in parent_map.items():
+        children.setdefault(parent_id, []).append(node_id)
+
+    # DFS traversal
+    result = []
+    stack = [root_id]
+    while stack:
+        node_id = stack.pop(0)
+        node = mapping.get(node_id, {})
+        msg = node.get("message")
+        if msg:
+            result.append(msg)
+        # Add children (take last child = newest branch)
+        node_children = children.get(node_id, [])
+        stack = node_children[-1:] + stack  # depth-first, prefer last branch
+
+    return result
+
+
+def _extract_text(content: dict) -> str:
+    """Extract plain text from a ChatGPT content block."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, dict):
+        content_type = content.get("content_type", "")
+        if content_type == "text":
+            parts = content.get("parts", [])
+            return " ".join(str(p) for p in parts if p)
+    return ""
+
+
+def list_conversations(path: str) -> list[dict]:
+    """List available conversations in an export file."""
+    raw = json.loads(Path(path).read_text())
+    conversations = raw if isinstance(raw, list) else [raw]
+    return [
+        {
+            "id": c.get("id", ""),
+            "title": c.get("title", "(untitled)"),
+            "message_count": len(c.get("mapping", {})),
+        }
+        for c in conversations
+    ]