Lacan Knowledge OS
A corpus-grounded research environment for Lacanian psychoanalysis.
Evidence first. Interpretation second. Fabrication never.
English · 中文 · Français · 日本語 · Deutsch · Italiano
The one rule this system is built around
Every claim must land on a passage number.
If the corpus cannot support a question, the system abstains — it does not answer
from model knowledge. An abstention is a result, not an error.
Table of contents
1. What it is
Lacan Knowledge OS is a local, offline-first research instrument for reading Lacan
seriously. It turns a corpus of seminar and écrits text into a citable evidence store,
and it puts a frozen scholarly core between your question and any answer.
Six things, one system:
| Capability | What it gives you |
|---|
| 🔎 | Research | Ask a question → the core retrieves passages, builds an evidence contract, and only then synthesises an answer whose every claim survives citation + entailment validation |
| 📖 | Explore | Read the corpus directly: passages, sessions, seminars, concepts, terminology — no model involved |
| 🔬 | Evidence Inspector | Answer → Claim → Passage → Session → Seminar → Witness/Source, with the exact quoted span and its context window |
| 🗂️ | Research Projects | Turn repeated runs into a long-term topic (questions, hypotheses, passages, persons, cases, bibliography) |
| 📚 | Bibliography & citations | Review status, metadata completeness, per-style citation availability with the reason it is unavailable |
| ✍️ | Obsidian bridge | Evidence and validation stay here; your understanding, notes and writing live in your vault |
2. Who it is for
- Researchers and doctoral students who need to cite Lacan precisely and to show
where a reading comes from.
- Study groups and reading seminars that want a shared, inspectable evidence base.
- Tool builders who want a worked example of a frozen-core architecture: a semantic
layer that cannot drift while a product layer evolves around it.
- AI engineers interested in grounded generation with an explicit abstention contract
instead of a confidence score.
3. What it refuses to do
These refusals are the design, not limitations:
| Refusal | Why |
|---|
| No answering from model knowledge | The synthesis step may only use retrieved evidence. If the contract is insufficient, the output is ABSTAINED. |
| No silent repair of sources | SOURCE_TRACE_INCOMPLETE stays visible. Hiding it would misrepresent the source. |
| No invented bibliographic data | Publisher, year, ISBN, page numbers are never guessed. A style that cannot be produced says why. |
| No auto-promotion to canonical | Imported or AI-produced material enters as a candidate and stays one until a human promotes it. |
| No unspecified semantics | The 39 scholarly components are hash-pinned; an undeclared change fails the freeze check and the system refuses to start. |
4. Quick start
This public edition ships the engine, not the corpus. See
§8 Bring your own corpus and CORPUS.md.
git clone https://github.com/YanKaFei/Lacan-Knowledge-OS.git
cd Lacan-Knowledge-OS
# 1) The interface boots with no corpus at all — Help Center + UI are fully usable:
python3 -m workspace_ui.server.cli --port 3090
# → http://127.0.0.1:3090/help 13-page Help Center
# → http://127.0.0.1:3090/research research surface (needs a corpus to answer)
# 2) Integrity checks (these are the contract, not decoration):
python3 _scripts/_tools/core_freeze.py --verify # 39 scholarly components
python3 _scripts/_tools/freeze_lineage.py --verify # semantic changes across phases
python3 _scripts/_tools/build_i18n.py --check # UI copy ↔ dictionary ↔ call sites
python3 _scripts/_tools/build_help.py --check # Help links, anchors, 0 fiction
# 3) Full regression (corpus-dependent suites need a corpus; see CORPUS.md)
bash _scripts/run_all_tests.sh
Requirements: Python 3.9+ (standard library only for the core path), a modern browser,
and — only if you want vector retrieval or a real LLM provider — the optional extras in
docs/EMBEDDING_PROVIDER.md. No bundler, no build step:
index.html loads ES modules directly.
5. How to use it
5.1 The task-based home page
Opening the system shows what you can do, not the system's internals:
Hero → [Start a research run] [First time here?]
Tasks → Ask a Lacanian question · Find text and sources · Study a concept
Study persons and cases · Build a long-term project · Manage sources
Workflow → ① Ask → ② Check evidence → ③ Read the original
→ ④ Save the material → ⑤ Sort sources → ⑥ Form your own knowledge
5 minutes → six steps to a finished first run
Every entry is a real link (/research, /explore, /projects, /bibliography,
/persons, /cases, /zotero, /help/...) — shareable, bookmarkable, openable in a new tab.
5.2 A complete research task
- Ask — one question per run.
- Read the state —
VALIDATED, VALIDATED_WITH_QUALIFICATIONS, PARTIALLY_SUPPORTED,
VALIDATION_FAILED, INSUFFICIENT_EVIDENCE, ABSTAINED. Read it literally.
- Verify — click a citation chip; the Evidence Inspector shows the quoted span, its
context window, and the source chain. The answer is what the core concluded; the
inspector is what the corpus actually says.
- Go deeper — open the same passage in Explore and read around it.
- Keep it —
Add to Project, or Save to Obsidian.
5.3 Help Center
/help is a 13-page centre with a sidebar, anchors, previous/next, and a topic search:
getting started, research, evidence, explore, research vs explore, projects,
persons & cases, bibliography, zotero, obsidian, languages, statuses, troubleshooting.
Every control name in Help is rendered from the real interface, and every functional
claim is machine-checked (HELP_CLAIM_VERIFICATION.json: 42/42 verified, 0 fiction, 0 pending).
5.4 Interface language vs research language
| Setting | Scope | Example |
|---|
Language (English / 中文) | The product interface only | switches instantly, no reload |
Research language (any / zh / fr / en) | The question language sent with a research request | does not translate the UI, does not filter retrieval |
Interface = 中文 + Research language = Français is a perfectly valid combination.
Lacan's original text, quoted passages and bibliographic metadata are never translated.
6. Architecture
your question
│
┌──────────▼───────────┐
│ PRODUCT LAYER │ workspace_ui/ · browse_api/ · project_api/
│ (may change freely) │ export_system/ · bibliography/ · obsidian_adapter/
└──────────┬───────────┘
│ scholarly_api v1 (product boundary — 3 hashed components)
┌──────────▼───────────┐
│ FROZEN CORE │ 39 hash-pinned components
│ (cannot drift) │ retrieval · evidence contract · sufficiency ·
└──────────┬───────────┘ synthesis boundary · citation · entailment · abstention
│
┌──────────▼───────────┐
│ CORPUS │ passage store · witnesses · ontology · indexes
│ (bring your own) │ NOT included in this repository
└──────────────────────┘
- Agents talk MCP, not Python.
mcp_server/ exposes 10 tools over stdio
(protocol 2025-11-25); the UI is just one client of that same contract.
- The freeze is executable.
core_freeze.py --verify recomputes 39 component hashes;
freeze_lineage.py --verify proves zero semantic change across seven phases.
- Derivatives are regenerable. SQLite/FTS/vector indexes and the 249k-passage store
are rebuildable from canonical sources + manifests. The vault is the source of truth.
Read more: docs/ARCHITECTURE.md ·
docs/MCP_ARCHITECTURE.md ·
HELP_SYSTEM_ARCHITECTURE.md.
7. Use it from DSH / any MCP client
The repository is a DeepSeek Harness plugin target:
it ships an MCP server, a portable row, and an installable DSH bundle.
# A. As a DSH plugin (installs the MCP row for you)
dsh plugin --profile web add github:YanKaFei/Lacan-Knowledge-OS
# B. Or paste the row yourself — integrations/lacan-kb-mcp.row.yml
# (tools then appear as mcp__lacan-kb__search_passages, …)
# C. Or run the server standalone
python3 _scripts/_tools/lacan-kb-mcp
Proven with DSH's own MCP SDK (_data/mcp/DSH_CLIENT_PROOF.json, 14/14 checks):
stdio handshake, 10 tools with schemas, mcp__lacan-kb__<tool> naming, structured evidence
returns, independent re-verification of returned passage ids, and a protocol error — not a
crash — for unknown tools. See docs/MCP_DSH_INTEGRATION.md.
8. Bring your own corpus (important)
Handing the corpus to a colleague. Build a pack and send it over a channel you control
(a private repo's release asset, your own server, a USB stick) — hash-verified and ~215 MB for
the reference corpus: docs/CORPUS_PACK.md
(tools/pack-corpus.py → tools/fetch-corpus.py).
This repository deliberately contains no source text:
| Not included | Why |
|---|
| Seminar/écrits full text (fr + zh) | Copyright of the rights holders |
Passage store (passages.jsonl, 249,105 records, ~384 MB) | Corpus text |
Witness realizations & witnesses (~152 MB) | Corpus text |
| Vector/lexical indexes | Large, rebuildable from your own corpus |
What is included: the schemas, the freeze contract, the builders, the validators and the
tests — i.e. everything needed to ingest text you are allowed to use (your own scans,
licensed editions, public-domain material, or your own translations).
python3 _scripts/build.py --help # corpus inventory & build entry points
python3 _scripts/inventory_corpus.py --help # canonical inventory + hashes
The public edition is produced and verified by
_scripts/_tools/build_public_edition.py:
an allow-list copy, then a negative verification (corpus N-gram probes, secret scan,
absolute-path scan, size gates). See docs/PUBLIC_EDITION.md.
9. Advantages and disadvantages
| ✅ Advantages | ⚠️ Disadvantages / limits |
|---|
|
Verifiability over fluency. Every claim is tied to a passage id; you can audit the
chain by hand.
Honest failure. Abstention, INSUFFICIENT_EVIDENCE and explicit unavailability are
first-class outputs. No hallucinated filler.
An executable contract. The 39-component freeze and the seven-segment lineage are
checked by code, not by a promise in a document.
Offline-first. Offline / Mock produces deterministic answers with no credentials and
no network.
One contract, many clients. The same MCP surface serves the web UI, DSH, and any
editor with an MCP client.
Auditable history. Every research run is an immutable snapshot; re-running a question
creates a new item instead of overwriting the old one.
Bilingual by construction. UI copy is dictionary-driven with 0 missing keys; source
text is deliberately never translated.
|
It needs a corpus you have the right to use. Out of the box it can show its interface,
its Help Centre and its contracts — but it cannot answer questions until you supply text.
It is opinionated about scope. It answers about a corpus. Questions about publication
history, attendees or dates will abstain, because the corpus does not carry that metadata.
No quality score. There is no "confidence %" anywhere; interpretation quality remains
your judgement.
Heavy for a laptop-scale workflow. The reference corpus is ~2.5 GB on disk including
derived indexes and embeddings.
Vector retrieval is optional and partial. Without the embedding extras, retrieval falls
back to lexical matching (the UI says which one is active).
Real-LLM synthesis is a single blocking call. Long runs take 45–60 s; the UI shows real
elapsed time, and "stop waiting" does not cancel the backend job.
Fast-moving product layer, frozen scholarly layer. Convenience features change often;
changing the semantics requires a formal Core Change Request.
Presupposes familiarity with the domain. The system will not teach you Lacan.
|
10. Status, roadmap, contributing
- Status: the scholarly core is frozen at v1 (
SCHOLARLY_CORE_READY); the product layer
is complete for daily use (research, explore, evidence, projects, bibliography, Zotero
import, Obsidian bridge, export, 6-language README, Help Centre).
- Verification numbers from the last acceptance run:
20/20 blocking gate items, 146 regression suites / 78 validators / 0 failed / 0 skipped,
core freeze PASS, semantic drift 0.
- Roadmap:
docs/ROADMAP.md.
- Contributing:
CONTRIBUTING.md — the one non-negotiable rule is
do not change scholarly semantics without a Core Change Request.
- Security:
SECURITY.md — credentials never pass through the product API.
License — code: Apache-2.0 · source texts: not distributed (NOTICE)
If this system saves you a week of citation checking, it did its job.
