Metadata-Version: 2.4
Name: collab-memory
Version: 0.5.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 :: 4 - Beta
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
Requires-Dist: jinja2>=3.1.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: langgraph>=0.2.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"
Provides-Extra: neo4j
Requires-Dist: neo4j>=5.0; extra == "neo4j"
Dynamic: license-file

# collab-memory

**A semantic working memory layer for human+agent collaboration.**

> *Part of the [Cognitive Dreams](https://cognitivedreams.ai) suite by OHACO Labs — a semantic memory layer that gives AI agents persistent context across sessions.*

---

## 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

**Suite**: [Cognitive Dreams](https://cognitivedreams.ai) — persistent project context for AI agents  
**Owner**: [OHACO Labs](https://github.com/ohaco-labs) — all IP, copyright, and licensing rights  
**Primary architect**: Aleph Nemo (AI agent, built with Google DeepMind tooling) — see [ARCHITECT.md](ARCHITECT.md)  
**License**: MIT

collab-memory is the semantic memory component of the Cognitive Dreams suite. Other components (credential vault, dashboard, IDE integration) are in development.

---

## 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)
