Metadata-Version: 2.4
Name: chicory-commons-man
Version: 0.1.0
Summary: Cross-project signal federation layer for Chicory memory systems
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/DMNK154/chicory-commons
Project-URL: Repository, https://github.com/DMNK154/chicory-commons
Project-URL: Issues, https://github.com/DMNK154/chicory-commons/issues
Keywords: llm,memory,mcp,chicory,federation,signals
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: chicory-man>=0.2.0
Dynamic: license-file

# Chicory Commons

Cross-project signal federation layer for [Chicory](https://pypi.org/project/chicory-man/) memory systems. Lets multiple Chicory instances share signals through a shared SQLite database, so the commons builds its own tensor network from cross-project activity.

## Install

```bash
pip install chicory-commons-man
```

This pulls in `chicory-man` as a dependency.

## How It Works

Each Chicory project instance emits **signals** when memories are stored, retrieved, or when synchronicities are detected. These signals are buffered and written to a shared commons SQLite database.

A **signal processor** reads pending signals and converts them into commons memories with dual tags:
- **Project-namespaced**: `projectname:tagname` (scoped to the source project)
- **Shared**: `tagname` (bridges across projects)
- **Meta**: `projectname`, `store`/`retrieve`/`synchronicity`

The commons database is itself a regular Chicory instance — all existing layers (trends, phase space, synchronicity detection, prime Ramsey lattice) operate on the signal-derived data.

## Configuration

Set these environment variables (or in `.env`):

```bash
CHICORY_COMMONS_ENABLED=true
CHICORY_COMMONS_DB_PATH=~/.chicory/commons.db
CHICORY_COMMONS_PROJECT_ID=my-project
```

## Backfill Existing Memories

To populate the commons with signals from an existing Chicory project:

```bash
chicory-commons-backfill --project-id my-project --project-db ~/.chicory/chicory.db --commons-db ~/.chicory/commons.db
```

## Components

- **SignalEmitter** — Buffers store/retrieve signals, flushes sync events immediately. Runs a background thread for periodic flushing.
- **SignalProcessor** — Reads pending signals from commons DB, converts to memories with dual-tag scheme, batch embeds.
- **backfill** — CLI tool to retroactively emit signals from existing project memories.
