anamnesis MCP server

// SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk = Anamnesis

image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] image:https://img.shields.io/badge/status-prototype-orange.svg[Prototype,link="PROTOTYPE.adoc"]

[WARNING]

Early-stage research prototype — not a product. Interfaces and heuristics are experimental and may change or be abandoned. It ingests conversation logs, which often contain other people's data and secrets — only feed in what you have the right to process, and review outputs before sharing. Interest, critique and collaboration are warmly welcome. + See link:PROTOTYPE.adoc[PROTOTYPE.adoc] for the full disclaimer and how this connects to the ethics work — https://github.com/hyperpolymath/phronesiser[Phronesiser] (normative constraints) and https://github.com/hyperpolymath/vexometer[Vexometer] (interaction ethics / UX).

A conversation knowledge extraction and reconciliation system for multi-LLM development workflows.

== Problem

Modern AI-assisted development creates chaos:

• Mixed-project conversations - Multiple projects discussed in single threads
• Dead-end tangents - Valuable ideas lost in conversation noise
• Lost context - Decisions and rationale buried across chat histories
• Artifact fragmentation - Code/docs created, modified, abandoned across sessions
• Multi-LLM mayhem - Switching between Claude, ChatGPT, Mistral with no unified view

== Solution

Anamnesis parses tangled multi-LLM discussion threads, tracks artifact lifecycles (created→modified→removed→evaluated), cross-links related fragments across conversations, and generates clean summaries with content properly bucketed by project/topic.

== Architecture

Multi-language functional system leveraging each language's strengths:

┌─────────────────────────────────────────────────────────────────┐
│  Data Sources: Claude, ChatGPT, Mistral, Git, Browser History  │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  Parser (OCaml): Angstrom combinators, type-safe format parsing│
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  Orchestrator (Elixir): OTP supervision, port pools, HTTP API  │
└────────────────────────┬────────────────────────────────────────┘
                         │
            ┌────────────┴────────────┐
            │                         │
            ▼                         ▼
┌───────────────────────┐  ┌──────────────────────────────────────┐
│ Reasoning (λProlog)   │  │ Analytics (Julia)                    │
│ - Artifact lifecycle  │  │ - RDF generation (Serd.jl)          │
│ - Contamination       │  │ - SPARQL queries (HTTP.jl)          │
│ - Fuzzy categorization│  │ - Reservoir computing (ESN)         │
│ - Meta-reasoning      │  │ - KBANN (knowledge-augmented nets)  │
└───────────┬───────────┘  └──────────┬───────────────────────────┘
            │                         │
            └────────────┬────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  Storage (Virtuoso): RDF triplestore, SPARQL 1.1, named graphs │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  Visualization (AffineScript): Reagraph graphs, timeline charts,   │
│  fuzzy category viz, type-safe functional React components     │
└─────────────────────────────────────────────────────────────────┘

== Technology Stack

Layer	Technology	Why
Parsing	OCaml (Angstrom, Atdgen)	Type safety, parser combinators, ELPI integration
Orchestration	Elixir/OTP	Fault tolerance, concurrency, supervision trees
Reasoning	λProlog (ELPI)	Higher-order abstract syntax, meta-reasoning
Analytics	Julia	Scientific computing without Python, RDF, reservoir computing
Storage	Virtuoso + SPARQL	RDF native, named graphs, inference
Visualization	AffineScript + React	Type safety, functional paradigm, eventual JS replacement

=== Critical Constraints

• ❌ NO PYTHON - Use Julia for all scientific computing
• ✅ Type safety throughout (OCaml, AffineScript, Elixir typespecs)
• ✅ Functional paradigm - Immutability, pure functions, declarative
• ✅ Multi-LLM from start (stub complexity initially)
• ✅ Academic rigor - Research-grade documentation

== Project Structure

.
├── CLAUDE.md                    # Claude Code guidance
├── README.md                    # This file
├── parser/                      # OCaml parsing components
│   ├── lib/parsers/            # Format-specific parsers
│   ├── bin/                    # Port executable
│   └── README.md
├── orchestrator/               # Elixir orchestration layer
│   ├── lib/anamnesis/         # Core logic
│   ├── lib/anamnesis_web/     # Phoenix HTTP API
│   └── README.md
├── reasoning/                  # λProlog meta-reasoning
│   ├── lifecycle/             # Artifact state machines
│   ├── categorization/        # Fuzzy membership, contamination
│   ├── linking/               # Cross-conversation references
│   ├── episodic/              # Memory queries
│   └── README.md
├── learning/                   # Julia analytics
│   ├── src/rdf/               # RDF manipulation
│   ├── src/reservoir/         # Reservoir computing, KBANN
│   ├── src/graphs/            # Graph processing
│   └── README.md
├── visualization/              # AffineScript UI
│   ├── src/components/        # React components
│   ├── src/bindings/          # JS library bindings
│   ├── src/types/             # Domain types
│   └── README.md
├── proving-ground/             # Test workspace
│   └── (zotero-voyant-export copy)
└── docs/
    ├── architecture/          # System architecture
    ├── research/              # Tech stack research
    ├── guides/                # Integration guides
    └── specifications/        # RDF schemas, protocols

== Getting Started

=== Prerequisites

• OCaml 5.0+ (via OPAM)
• Elixir 1.15+ (via asdf or package manager)
• Julia 1.10+ (via juliaup)
• Node.js 18+ (for AffineScript)
• Virtuoso 7+ (via Docker or native)

=== Quick Start

= 1. Install language runtimes (see component READMEs)

= 2. Build parser (OCaml)

cd parser
opam install --deps-only .
dune build

= 3. Build orchestrator (Elixir)

cd ../orchestrator
mix deps.get
mix compile

= 4. Build reasoning (λProlog via OCaml/ELPI)

cd ../reasoning
dune build

= 5. Setup analytics (Julia)

cd ../learning
julia --project=. -e 'using Pkg; Pkg.instantiate()'

= 6. Build visualization (AffineScript)

cd ../visualization
npm install
npm run res:build

= 7. Start Virtuoso (Docker)

docker run -d -p 8890:8890 -p 1111:1111 \
  -e DBA_PASSWORD=anamnesis \
  --name virtuoso \
  openlink/virtuoso-opensource-7

= 8. Run Anamnesis

cd ../orchestrator
mix phx.server
= Visit http://localhost:4000

== Current Status

Phase: Initial Implementation

=== Completed ✅

• Project architecture designed
• Comprehensive tech stack research (6 detailed reports)
• Directory structure created
• Component READMEs written
• CLAUDE.md guidance created
• OCaml Claude parser implemented
• Elixir port infrastructure
• Julia RDF modules (schema, serialization, SPARQL, Virtuoso)
• Julia reservoir computing modules (ESN, embeddings)
• Julia graph analysis modules
• AffineScript domain types and color mixing

=== In Progress 🚧

• End-to-end integration testing
• λProlog reasoning module implementation
• Virtuoso storage integration
• Additional LLM format parsers (ChatGPT, Mistral)

=== Phase 1 Roadmap 📋

1. ✅ Create Anamnesis repository
2. ✅ Research tech options (Julia RDF, reservoir computing, AffineScript viz, OCaml parsers, λProlog)
3. ⬜ Copy proving ground (zotero-voyant-export)
4. ✅ Setup basic infrastructure (build systems, test frameworks)
5. 🚧 Milestone 1: Parse single Claude conversation JSON → Virtuoso RDF triples

=== Phase 2: Milestone 1 🎯

Goal: End-to-end pipeline for one conversation format

• Claude JSON format parser (OCaml)
• Port communication (OCaml ↔ Elixir)
• Basic RDF generation (Julia)
• Virtuoso storage integration
• Simple graph visualization (AffineScript)

== Key Design Concepts

=== Multi-Category Membership

Conversations don't belong to just one project. Anamnesis supports fuzzy boundaries:

anamnesis:conv:123 anamnesis:belongsTo anamnesis:proj:anamnesis ;
                   anamnesis:membershipStrength 0.8 .

anamnesis:conv:123 anamnesis:belongsTo anamnesis:proj:affinescript-evangeliser ;
                   anamnesis:membershipStrength 0.3 .

Visualized via color mixing: 80% green (Anamnesis) + 30% orange (AffineScript) = blended color.

=== Artifact Lifecycle Tracking

Track state transitions over time:

% λProlog rules
valid_transition created modified.
valid_transition modified evaluated.
valid_transition modified removed.

current_state artifact_123 timestamp_456 State.
% State = modified

=== Cross-Conversation Linking

Fragment references span conversations:

= SPARQL query

SELECT ?conv1 ?conv2 ?artifact
WHERE {
  GRAPH ?g1 { ?conv1 anamnesis:discusses ?artifact . }
  GRAPH ?g2 { ?conv2 anamnesis:discusses ?artifact . }
  FILTER(?conv1 != ?conv2)
}

=== Episodic Memory

Named graphs partition conversations by episode:

graph:conversation:uuid-1  # Conversation metadata
graph:artifacts:uuid-1     # Artifact lifecycles
graph:links:uuid-1         # Cross-references
graph:categories:uuid-1    # Project membership

== Documentation

• Architecture: /docs/architecture/system-architecture.adoc - Complete system design
• Research: /docs/research/ - Tech stack evaluations:
  • julia-rdf-ecosystem.adoc - RDF libraries (Serd.jl recommended)
  • julia-reservoir-computing.adoc - ESN, KBANN (ReservoirComputing.jl)
  • puppygraph-evaluation.adoc - Property graphs vs RDF (stick with Virtuoso)
  • affinescript-visualization.adoc - Reagraph, affinescript-recharts
  • ocaml-parsing-elixir-bridge.adoc - Angstrom, ports vs NIFs
  • lambda-prolog-meta-reasoning.adoc - ELPI, HOAS, integration
• Component READMEs: Each directory has detailed setup/usage docs
• CLAUDE.md: Guidance for Claude Code when working on this project

== Testing

=== Proving Ground

The zotero-voyant-export repository is our test case - it's contaminated with Anamnesis planning discussions mixed into Zotero export tool development. This IS the problem we're solving.

Strategy:

1. Copy entire repo to proving-ground/
2. Preserve original
3. Run Anamnesis pipeline
4. Verify correct untangling
5. Store iterations for comparison

=== Test Coverage Targets

• Parser: 90%+ (property-based testing with qcheck)
• Orchestrator: 85%+ (ExUnit + StreamData)
• Analytics: 80%+ (Test.jl)
• Visualization: 75%+ (Jest + React Testing Library)
• Reasoning: Example-driven (λProlog test harness)

== Performance Targets

Component	Target	Strategy
Parser throughput	100 conversations/sec	Parallel ports, incremental parsing
λProlog queries	<100ms	ETS caching, tabled predicates
SPARQL queries	<50ms simple, <500ms complex	Virtuoso indexing
Graph viz	1000-5000 nodes interactive	WebGL (Reagraph), LOD
RDF storage	10M+ triples	Named graph partitioning

== Related Projects

• AffineScript Evangeliser - Learning curve synergies
• Zotero:NSAI - Neurosymbolic AI integration
• Fogbinder - Uncertainty-as-feature framework

== Contributing

This is a personal research project, but architecture decisions are documented for transparency. See component READMEs for development guidelines.

== Academic Context

Relevant to user's research/journalism work:

• Agnotology - Study of culturally-induced ignorance
• Axiology - Theory of value
• Ethics - Moral philosophy applications
• Knowledge representation - Formal semantics, RDF, logic programming

== License

To be determined.

== Resources

• Repository: https://github.com/Hyperpolymath/anamnesis
• Test Case: zotero-voyant-export (to be copied to proving-ground)
• Handover Docs: zotero-voyant-export/docs/contamination-notice/
  • ANAMNESIS_HANDOVER_MINIMAL.adoc
  • THREAD_CONTAMINATION_WARNING.adoc

---

Status: Initial implementation phase. Core infrastructure complete, working toward Milestone 1.

Next Immediate Steps: Complete end-to-end testing and Virtuoso integration.

== Architecture

See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.