Metadata-Version: 2.3
Name: docmancer
Version: 0.7.9
Summary: Compress local documentation context for coding agents.
License: MIT License
        
        Copyright (c) 2026 Docs Kit Limited
        
        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.
Requires-Python: <3.14,>=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: charset-normalizer>=3.3.0
Requires-Dist: click>=8.0.0
Requires-Dist: filelock>=3.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: keyring<26.0.0,>=25.7.0
Requires-Dist: markdownify>=0.13.0
Requires-Dist: model2vec>=0.3.0
Requires-Dist: pdfplumber>=0.11.0
Requires-Dist: pydantic-settings>=2.2.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pynacl<2.0.0,>=1.6.2
Requires-Dist: pypdf>=4.0.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rfc8785<0.2.0,>=0.1.4
Requires-Dist: sqlite-vec>=0.1.0
Requires-Dist: striprtf>=0.0.26
Requires-Dist: textual<9.0.0,>=8.0.0
Requires-Dist: trafilatura>=2.0.0
Requires-Dist: ultimate-sitemap-parser>=0.12
Requires-Dist: w3lib>=2.0.0
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == 'browser'
Provides-Extra: crawl4ai
Requires-Dist: crawl4ai>=0.4.0; extra == 'crawl4ai'
Provides-Extra: dev
Requires-Dist: fastembed>=0.4.0; extra == 'dev'
Requires-Dist: mcp>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: qdrant-client>=1.10.0; extra == 'dev'
Requires-Dist: sse-starlette<3.1.0,>=1.6.1; extra == 'dev'
Requires-Dist: starlette<0.42.0,>=0.40.0; extra == 'dev'
Provides-Extra: embeddings-cohere
Requires-Dist: cohere>=5.0.0; extra == 'embeddings-cohere'
Provides-Extra: embeddings-heavy
Requires-Dist: fastembed>=0.4.0; extra == 'embeddings-heavy'
Requires-Dist: qdrant-client>=1.10.0; extra == 'embeddings-heavy'
Provides-Extra: embeddings-openai
Requires-Dist: openai>=1.0.0; extra == 'embeddings-openai'
Provides-Extra: embeddings-voyage
Requires-Dist: voyageai>=0.2.0; extra == 'embeddings-voyage'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Requires-Dist: sse-starlette<3.1.0,>=1.6.1; extra == 'mcp'
Requires-Dist: starlette<0.42.0,>=0.40.0; extra == 'mcp'
Description-Content-Type: text/markdown

<div align="center">

**Your agents' memory, reconciled, reviewable, and shared.**

[![PyPI version](https://img.shields.io/pypi/v/docmancer?style=for-the-badge)](https://pypi.org/project/docmancer/)
[![License: MIT](https://img.shields.io/github/license/docmancer/docmancer?style=for-the-badge)](https://github.com/docmancer/docmancer/blob/main/LICENSE)
[![Python 3.11 | 3.12 | 3.13](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/docmancer/)

[Install](#install) | [Context packs](#canonical-context-packs) | [Commands](#command-line) | [Cloud](#optional-encrypted-cloud-sync) | [Wiki](./wiki/Home.md)

<img src="readme-assets/tui-readme.gif" alt="Docmancer terminal explorer" style="width: 92%; max-width: 1120px; height: auto;" />

</div>

Claude Code, Codex, Cursor, Gemini, OpenCode, Cline, Windsurf, and other coding agents already write memory, instructions, and rules across your machine. Docmancer harvests that evidence into one local index, reconciles duplicates and revision history, and proposes approved context that every installed agent can use.

Raw memory is evidence, not the source of truth. Approved context remains a set of individually editable Markdown records grouped by versioned pack manifests. This keeps provenance and review granular without generating one enormous memory file.

The default path is local and keyless. SQLite FTS5, the packaged `potion-base-8M` model, and `sqlite-vec` provide hybrid retrieval without a daemon or model download.

## Install

```bash
pipx install docmancer --python python3.13
docmancer setup
docmancer
```

Bare `docmancer` opens with a startup screen while local memory and indexes are loaded, then opens the three-pane terminal interface. It has four top-level tabs:

- **Context** shows Personal defaults, This project, Team standards, Team project, and pending review.
- **Sources** shows agent memory, instructions, rules, provenance, and inline security warnings.
- **Audit** is the first-class home for masked security findings, automatic context delivery, and optional new-memory capture coverage for Claude Code and Codex.
- **Docs** keeps documentation browsing and search separate from memory.

The available slash commands are `/sync`, `/distill`, `/review`, `/add`, `/share`, `/status`, `/settings`, and `/help`. Plain text searches the active tab. Visible buttons and keybindings handle selection-specific actions. Any button that starts work immediately shows an animated busy state and ignores repeat clicks until the action finishes.

Context opens on **Personal context** because Personal defaults contains everyday preferences and This project contains local exceptions. Team standards and Team project remain available from the View selector, but stay visually secondary until you share context. Each context area shows a compact summary, while approved statements appear as paginated rows that can be inspected, edited, or removed individually. Actions are contextual: context summaries show Add and Share when applicable, statements show Edit and Remove, and pending changes show Approve and Reject. Mutations display an animated progress state and disable their buttons until the operation finishes.

The left pane shows approved Personal and Team counts. **Reset Personal** removes personal defaults and current-project context immediately, rejects their pending proposals, and writes tombstones. **Reset Team** creates removal proposals because team changes still require approval. Neither reset changes the raw source corpus.

In Audit, the left pane shows persistent Claude Code and Codex automatic-context coverage. Select an agent card for its effective configuration, or choose **How it works** for a concise explanation. The middle pane is reserved for security findings and severity filtering.

## First run: activate your context

Seeing `0 active` in the Context tab is normal after setup. Sources are evidence, and Docmancer does not silently turn harvested agent memory into approved context. You must review the proposed changes once before they become active and reach your agents.

In the TUI:

1. Run `/sync` to harvest current sources and reconcile them.
2. Open **Context**. If you see a **PENDING REVIEW** row, select it to inspect the proposed statements.
3. Choose **APPROVE** to activate the proposal, or **REJECT** to discard it.
4. If there is no pending proposal, run `/distill` first, then review the new proposal.

After approval, the destination pack changes from `0 active` to the number of approved statements. A later `/sync` refreshes managed agent projections automatically. You can also run `docmancer agent refresh` explicitly.

The equivalent CLI flow is:

```bash
docmancer sync --local-only
docmancer memory review
docmancer memory review <proposal-id>
docmancer memory review <proposal-id> --approve
docmancer memory show personal-defaults
docmancer agent refresh
```

Personal defaults and Current project fill only after you approve personal proposals or add context directly. Team standards and Team project remain empty until personal context is shared and the resulting team proposal is approved.

## Canonical context packs

Docmancer creates four default packs:

| Pack | Audience | Applicability |
| --- | --- | --- |
| Personal defaults | Personal | Global |
| Current project | Personal | Project |
| Team standards | Team | Global |
| Team project | Team | Project |

Each approved statement is one revisioned Markdown record. Pack manifests store stable pack identity, ordered record references, scope, revision lineage, and publication state. Rendered pack documents are disposable views.

```bash
docmancer sync
docmancer memory distill --into personal-defaults
docmancer memory review
docmancer memory review <proposal-id> --approve
docmancer memory show personal-defaults
```

Distillation produces a patch with additions, semantic consolidations, removals, project overrides, unresolved contradictions, source paths, and confidence. Personal defaults admit durable preferences, constraints, workflows, and commands rather than paginating through one-off task history. Exact duplicates and explicit revision lineage reconcile automatically. New canonical statements, semantic merges, contradiction winners, and team changes require review.

Default distillation evaluates the complete eligible corpus and has no arbitrary operation cap. Pack manifests record the fully reviewed evidence fingerprint, and each approved record retains its contributing source-atom identity. When the complete evidence set has been reviewed and has not changed, another distill produces no patch. The optional CLI `--limit` creates a review batch instead. After that batch is approved or rejected, the next distill continues with the remaining evidence.

## Automatic agent delivery

Approved context is compiled with this precedence:

1. Team project context
2. Personal project context
3. Team standards
4. Personal defaults
5. Relevant non-canonical evidence

Hooks inject compiled context automatically for agents that support them. Other installed agents receive the same approved context through a managed projection. Projections are disposable outputs and are never harvested as sources of truth.

```bash
docmancer agent install claude-code --hooks
docmancer agent install codex --hooks
docmancer agent install cursor
docmancer agent refresh
```

`docmancer sync` also refreshes installed projections. It never copies the complete raw corpus into agent files.

## Team workflow

Sharing always creates a review proposal:

```bash
docmancer memory share personal-defaults
docmancer memory review
docmancer memory review <proposal-id> --approve
docmancer memory show team-standards
```

Reviewers can approve, reject, or edit proposed operations. Approval creates team-owned canonical records and revises the destination manifest. Project-level exceptions remain in a project pack and can explicitly reference the inherited standard they override.

Personal record edits activate immediately. Team record edits and removals become proposals. Removing approved context writes a content-free tombstone so replayed cloud revisions cannot resurrect it.

## Command line

The public root surface is intentionally small:

```text
docmancer
docmancer setup
docmancer sync [--local-only]
docmancer query <TEXT>
docmancer memory
docmancer docs
docmancer status [--check]
docmancer cloud
docmancer agent
docmancer mcp
```

Memory actions:

```text
docmancer memory show [PACK_OR_ID]
docmancer memory add <TEXT> [--into PACK]
docmancer memory edit <ID> [TEXT]
docmancer memory remove <ID>
docmancer memory distill [--into PACK]
docmancer memory review [PROPOSAL]
docmancer memory share <PACK>
docmancer memory export [PACK]
```

Documentation actions live under one namespace:

```bash
docmancer docs add ./docs
docmancer docs add https://docs.pytest.org
docmancer docs query "How do I parametrize a fixture?"
docmancer docs list
docmancer docs sync
docmancer docs remove <source>
```

Older commands remain as hidden compatibility aliases for one release and print their replacement to standard error.

## Status and security

```bash
docmancer status
docmancer status --check
docmancer status --json
```

Status combines index health, source and harness coverage, masked security findings, installed-agent delivery, pending reviews, and cloud state. Secret values are redacted before durable writes, indexing, provider calls, or cloud encryption.

## Optional encrypted cloud sync

Cloud sync is optional and never gates local capture, recall, MCP, docs, or Git export.

```text
docmancer cloud
docmancer cloud connect
docmancer cloud sync
docmancer cloud devices
docmancer cloud devices --approve <device-id> --fingerprint <fingerprint>
docmancer cloud devices --revoke <device-id>
docmancer cloud relay --project "$PWD"
docmancer cloud disconnect
```

The device list shows each registration's state, full device ID, fingerprint, key version, last-seen time, enrolment time, and which registration belongs to the current CLI. Revocation blocks that registration from future Cloud sync but cannot erase memory or keys it already held. Docmancer will not revoke the last approved device.

Protocol v1 synchronizes durable record revisions and tombstones. Protocol v2 synchronizes atoms, relations, overrides, pack manifests, and review proposals as encrypted graph objects. The server receives opaque encrypted envelopes and routing metadata. It never receives plaintext memory, tags, pack content, local paths, raw local IDs, private keys, workspace keys, or recovery keys.

The unlocked Cloud workbench can browse and change the synced graph in the browser. Operations that need local files, the local index, documentation, hooks, audit, or provider credentials use an explicit local relay:

```bash
# Read-only local actions
docmancer cloud relay --project "$PWD"

# Also allow browser-confirmed actions that change local state
docmancer cloud relay --project "$PWD" --allow-writes
```

The relay makes outbound HTTPS requests only and does not open a local port. Action names, arguments, results, query text, and local paths are encrypted with the workspace key and signed by the sending device. The server sees delivery metadata and ciphertext. Browser requests expire after two minutes, the server rejects any expiry beyond five minutes, and expired relay ciphertext is pruned after 24 hours.

The browser can request only a fixed Docmancer action allowlist, never a Python method or shell command. The relay blocks local mutations by default. A supported write requires confirmation in the browser and a relay started with `--allow-writes`. Destructive or overwrite-prone operations, including forgetting memory, resetting context, clearing indexes, editing or deleting source files, and applying generated context, stay in the local CLI or TUI so their full confirmation flows remain visible. Closing the command stops the device from accepting new work. The relay is part of the paid hosted sync service; the complete local CLI, TUI, MCP, capture, recall, source management, docs, audit, and Git workflow remain free.

Decrypted local caches support offline recall. Markdown export remains available for review, backup, and leaving the service.

## Where data lives

- `~/.docmancer/memory.db` is the rebuildable local search and graph index.
- `~/.docmancer/memories/*.md` contains personal canonical records.
- `~/.docmancer/context/team-memory/*.md` contains locally decrypted team-wide records.
- `~/.docmancer/context/packs/*.yaml` contains versioned pack manifests.
- `~/.docmancer/context/proposals/*.yaml` contains review proposals.
- `<repo>/.docmancer/memory/*.md` remains the Git-reviewable team project store.
- `~/.docmancer/memory-tombstones.json` contains content-free suppression identities and hashes.

There is no telemetry. Local commands do not phone home. Network access occurs only for explicit cloud sync, documentation fetches, or optional provider-backed operations.

## More documentation

See the [wiki](./wiki/Home.md) for architecture, supported sources, installation targets, configuration, cloud recovery, and troubleshooting.
