io.github.base76-research-lab/cognos-session-memory
CognOS trust scoring (C=p·(1-Ue-Ua)) and session trace storage as MCP tools.
Open source Open in the app JSON README (API)
About
CognOS trust scoring (C=p·(1-Ue-Ua)) and session trace storage as MCP tools.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- base76-research-lab
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Stars
- 1
- Last push
- 2026-03-03T11:56:33Z
- Repository state
- arquivado
- Language
- Python
- Added
- 2026-08-29 03:02:28
- Updated
- 2026-08-29 03:02:28
- Origin id
io.github.base76-research-lab/cognos-session-memory
README
# CognOS Session Memory
mcp-name: io.github.base76-research-lab/cognos-session-memory
**Verified context injection via epistemic trust scoring for LLMs.**
Solves session fragmentation by maintaining verified, high-confidence session context between conversations.
## Problem
Large language models suffer from **session fragmentation**: each new conversation starts without verified context of previous work. This forces repeated explanations, loses decision history, and breaks long-running workflows.
Existing solutions (persistent memory systems, vector retrieval) either:
- Lack trust scores before injection → hallucinations propagate
- Don't audit which context was injected → compliance gaps
- Treat all past information equally → noise overwhelms signal
## Solution
A **plan-mode gateway** that:
1. **Extracts** structured context from 3-5 recent traces
2. **Scores** context quality via CognOS epistemic formula: `C = p · (1 − Ue − Ua)`
3. **Injects** as system prompt only if `C > threshold`
4. **Flags** for manual review if `C < threshold`
5. **Audits** every context injection with trace IDs → EU AI Act compliance
## Architecture
```
recent_traces (n=5)
↓
extract_context() → ContextField + coverage
↓
compute_trust_score(p, ue, ua) → C, R, decision
↓
if C > threshold:
system_prompt ← inject
else:
flagged_reason ← manual review
```
### Core Formula
```
C = p · (1 − Ue − Ua)
R = 1 − C
where:
p = prediction confidence (coverage of required fields)
Ue = epistemic uncertainty (divergence between traces)
Ua = aleatoric uncertainty (mean risk in traces)
```
### Action Gate
```
R < 0.25 → PASS (inject without review)
0.25 ≤ R < 0.60 → REFINE (inject with caution)
R ≥ 0.60 → ESCALATE (flag for manual review)
```
## API
### POST /v1/plan
Extract and score context.
**Request:**
```json
{
"n": 5,
"trust_threshold": 0.75,
"mode": "auto"
}
```
**Response (if injected):**
```json
{
"status": "injected",
"trust_score": 0.82,
"confidence": 0.82,
"risk": 0.18,
"decision": "PASS",
"context": {
"active_project": "CognOS mHC research",
"last_decision": "Verify P1 hypothesis",
"open_questions": ["How does routing entropy scale?"],
"current_output": "exp_008 complete",
"recent_models": ["gpt-4", "claude-3", "mistral"]
},
"system_prompt": "## CognOS Context...",
"trace_ids": ["uuid-1", "uuid-2", ...]
}
```
**Response (if flagged):**
```json
{
"status": "flagged",
"trust_score": 0.45,
"decision": "REFINE",
"flagged_reason": "Trust score 0.45 below threshold 0.75. Manual review recommended.",
"trace_ids": [...]
}
```
## Modes
- **auto** (default) — inject if `trust_score ≥ threshold`, else flag
- **force** — always inject (for testing)
- **dry_run** — compute score but never inject
## Claude Code Integration
### As a /compact replacement
```bash
# In any Claude Code session:
/save
```
Claude writes a structured summary, trust-scores it, and persists it to SQLite.
Next session: automatically injected as `SESSION_CONTEXT` before your first prompt.
See [docs/COMPACT_ALTERNATIVE.md](docs/COMPACT_ALTERNATIVE.md) for a full comparison.
### As an MCP server
Add to `~/.claude/settings.json`:
```json
{
"mcpServers": {
"cognos-session-memory": {
"command": "python3",
"args": ["/path/to/cognos-session-memory/mcp_server.py"]
}
}
}
```
Tools exposed:
| Tool | Description |
|------|-------------|
| `save_session(summary, project?)` | Trust-score and persist a session summary |
| `load_session(threshold?)` | Retrieve last verified context (default threshold: 0.45) |
---
## Quick Start
### Installation
```bash
git clone https://github.com/base76-research-lab/cognos-session-memory
cd cognos-session-memory
pip install -e .
```
### Run Gateway
```bash
python3 -m uvicorn --app-dir src main:app --port 8788
```
### Test /v1/plan (dry_run)
```bash
curl -X POST http://127.0.0.1:8788/v1/plan \
-H 'Content-Type: application/json' \
-d '{"n": 5, "mode": "dry_run"}'
```
### Test /v1/plan (auto)
```bash
curl -X POST http://127.0.0.1:8788/v1/plan \
-H 'Content-Type: application/json' \
-d '{"n": 5, "trust_threshold": 0.75, "mode": "auto"}'
```
## Modules
- **trust.py** — CognOS confidence formula, action gate, signal extractors
- **trace_store.py** — SQLite persistence (write/read/purge)
- **plan.py** — Context extraction, trust scoring, system prompt building
- **main.py** — FastAPI gateway + middleware
- **mcp_server.py** — MCP stdio server (`save_session`, `load_session`)
## Testing
```bash
pytest tests/ -v --cov=src
```
## Documentation
- [COMPACT_ALTERNATIVE.md](docs/COMPACT_ALTERNATIVE.md) — Why this beats `/compact`
- [PAPER.md](docs/PAPER.md) — Research paper
## Research Paper
See [docs/PAPER.md](docs/PAPER.md) — "Verified Context Injection: Epistemically Scored Session Memory for Large Language Models"
**Status:** Independent research — Base76 Research Lab, 2026
**Authors:** Björn André Wikström (Base76)
## Citation
```bibtex
@software{wikstrom2026cognos,
author = {Wikström, Björn André},
title = {{CognOS Session Memory}: Verified Context Injection via Epistemic Trust Scoring},
year = {2026},
url = {https://github.com/base76-research-lab/cognos-session-memory}
}
```
## License
MIT
## Contact
- **Author:** Björn André Wikström
- **Email:** bjorn@base76.se
- **ORCID:** 0009-0000-4015-2357
- **GitHub:** [base76-research-lab](https://github.com/base76-research-lab)